UpNext design system — living documentation

This folder is the team's shared brain for the design system. It lives in the repo so it can't drift out of sync, and it's rendered inside the playground at /library/docs so you read it next to the components it describes.

How to read this

If you're new to design systems in code, read these in order:

1. Why this exists — the problem we're solving, and why the system matters.
2. The architecture — three layers (primitives → wrappers → app) and why we wrap instead of using shadcn directly.
3. Working with tokens — primitive vs semantic, the only-touch-the-semantics rule.
4. States and interaction — every hover/focus/active state maps to a deliberate palette step. No random darken filters.
5. Adding a component — engineer walkthrough for wrapping a new shadcn primitive.
6. Changing a token — designer walkthrough for retheming safely.
7. The migration playbook — how this moves into the real UpNext app, phase by phase.
8. Glossary — the vocabulary, defined once.

Audience

These docs speak to both designers and engineers. Sections that need code knowledge are clearly labeled Engineer note:. Sections that involve design judgment are labeled Designer note:. Everyone should be able to read the whole thing — the system only works if both sides understand it.

When to update these docs

Update a doc the same PR you change the thing it describes. The docs are part of the system, not commentary on it. If they fall out of sync, the system breaks down — people stop trusting them, then stop reading them, then the conventions erode.

Specific triggers:

• Add a token → update working-with-tokens.md
• Add a wrapper → update adding-a-component.md only if the pattern changed
• Change a state-color rule → update states-and-interaction.md
• Discover a migration gotcha → add to the-migration.md