feat(design-system): build a shared, versioned tokens package consumed by the docs site and showcase

[salazarsebas]

Part of #241

Background

The docs site and showcase (per the repository strategy) are two independently deployed static builds, potentially in the same repository or split, that must never visually diverge. Defining palette/type/spacing values on paper (sibling sub-issue) does not, by itself, prevent two builds from drifting; it needs to be a real, single, importable source both consume.

Objective

Package the design tokens defined in the sibling sub-issue as a small, versioned artifact (a CSS custom-properties file, or an npm package if the site tooling is Node-based) that both the documentation site and the showcase generator import directly, rather than each hand-copying values.

References

• Style Dictionary, for transforming one token source into multiple output formats if needed: https://amzn.github.io/style-dictionary/
• Sibling sub-issue's docs/BRAND.md (the source of truth this package encodes)
• Repository strategy, for how a cross-repo shared package should be distributed if the docs site and showcase end up split across repositories: docs/strategy/10-repository-strategy.md

In scope

1. A single tokens source file (format decided in the PR: CSS custom properties is the simplest option if both consumers are static HTML/CSS builds; an npm package is preferable only if there's a build-time transform need) encoding every value from docs/BRAND.md.
2. Both light and dark mode token sets, structured so consumers can switch via a prefers-color-scheme media query and a data-theme attribute override, consistent with how the token set will actually be consumed by static site CSS.
3. Integration into at least one real consumer (the docs site, once its scaffold sub-issue lands) as proof the package actually works end to end, not just published in isolation.
4. A versioning and update policy documented (e.g. semver, changelog) so the docs site and showcase can each pin or upgrade independently without silent drift.

Out of scope

• Applying the tokens retroactively to README.md or other root-level Markdown; this issue ships the package, application to every surface is incremental follow-up work.

Definition of done

• Tokens package exists, versioned, with both light and dark values for every token defined in docs/BRAND.md.
• At least one real site/build consumes it and visibly reflects a token change when the package is updated.

[Emoji-dot]

@Emoji-dot has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

I would like to work on this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Emoji-dot to this issue.

[Damilorlar]

@Damilorlar has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

I would love to work on this project.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Damilorlar to this issue.

[sladeoj]

@sladeoj has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

hello maintainer i would love to work on this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @sladeoj to this issue.

[abrahambaba1]

@abrahambaba1 has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

Having read the description of the issue, I believe it matches my experiences as a developer and I would love to contribute

ℹ️ Repo Maintainers: To accept this application, review their application or assign @abrahambaba1 to this issue.

[bashir347]

@bashir347 has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

Hi maintainer I would like to work on this issues

ℹ️ Repo Maintainers: To accept this application, review their application or assign @bashir347 to this issue.

[Spagero763]

@Spagero763 has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

I would like to take up this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Spagero763 to this issue.

[drips-wave]

Congratulations, @Spagero763! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on July 30, 2026.

🧑‍💻 @Spagero763: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[drips-wave]

This issue has been marked as completed by a Drips Wave moderator for @Spagero763 as part of the Stellar Wave Program's 7th Wave 🥳

Moderator's reason: Points issued via /assess-issue override (AI decision: ESCALATE)

😎 @Spagero763: You earned 200 Points for completing this issue! After the current Wave ends, you'll be eligible for a percentage of the Wave's reward pool based on the percentage of total points you've earned. Learn more here.

🧑‍💻 Repo maintainers: How'd the contributor do? Leave a review to share your experience working with them.

ℹ️ Note: This issue was marked complete via moderation. Points were issued even though the GitHub issue remains open.