feat: add structured shadows/elevation token category

[SomSamantray]

Summary

Adds a structured shadows: token category to the DESIGN.md spec, giving shadow/elevation values the same first-class treatment colors, typography, rounded, and spacing already have: a schema, model resolution, lint validation, generated spec docs, and an example.

Closes #92.

What's in here

• Schema (spec-config.yaml/.ts): a shadow_properties definition (offsetX, offsetY, blur, spread, color) and a boxShadow component sub-token, mirroring the existing typography_properties pattern.
• Model (model/spec.ts, model/handler.ts): a composite ResolvedShadow type resolved the same way typography is — each dimension sub-field is unit-validated (px/rem/em, matching typography/rounded/spacing), and color accepts either a literal CSS color or a {colors.*} token reference, resolved through the existing reference-chasing logic.
• Parser (parser/spec.ts, parser/handler.ts): shadows recognized as a known top-level key (typo suggestions via the existing unknown-key rule pick it up automatically).
• Lint: a new shadow-orphaned rule flags shadow tokens never referenced by a component, sharing a computeReferencedPaths helper with the existing orphaned-tokens rule rather than duplicating the reference-scan.
• Docs: spec.mdx gained a ### Design Tokens subsection under Elevation & Depth; docs/spec.md was regenerated via bun run spec:gen (never hand-edited).
• Example: examples/paws-and-paths/DESIGN.md now has a shadows.card token referenced from card-profile.boxShadow.

Review notes

This went through an internal simplify + multi-lens review pass before opening. Two things worth flagging for reviewers:

• Fixed a crash path where an empty/malformed shadow entry (e.g. shadows.broken: with no value) would throw inside parsing, get caught by the model's outer try/catch, and silently discard all findings for the entire file — now it emits a scoped error instead.
• Dimension sub-fields (offsetX/offsetY/blur/spread) now resolve {rounded.*}/{spacing.*} token references the same way color resolves {colors.*} — previously a token reference on those fields was silently dropped with no value and no diagnostic.

Testing

• bun test — 331 pass, 0 fail (up from the pre-change 310; new coverage for happy path, chained/indirect color references, non-color reference rejection, malformed input, and unit validation).
• bunx tsc --noEmit clean.
• bun run spec:gen --check confirms the generated doc is deterministic.
• Updated example lints with 0 errors, 0 warnings via design.md lint.

---

_{🤖 Assisted by Compound Engineering}

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[SomSamantray]

@googlebot I signed it!

[SomSamantray]

CLA signed and confirmed. Pushed an empty commit to retrigger checks.

[zachshallbetter]

Hi @SomSamantray, this draft looks really clean!

Standardizing structured shadows is a great way to bridge the elevation gap mentioned in PHILOSOPHY.md.

I noticed that the exporters (css-vars and tailwind-v4) don't seem to serialize the new category yet. To make it functional for downstream projects, we'll need to compile the composite shadow properties (offsetX, offsetY, blur, spread, and color) into a standard CSS box-shadow string (e.g. offsetX offsetY blur spread color) inside the handlers.

Are you planning to add the exporter support to this draft, or would you mind if I opened a follow-up PR to handle the serialization once this is merged?

Happy to help out if you'd like.

[SomSamantray]

@zachshallbetter

You can go ahead and open a follow-up PR to handle the serialization!

Fell free to!