Define a design token architecture

Token systems break in familiar ways: components reference raw values like blue-500 directly, so a dark theme means editing every component; names describe the value (color-light-grey) instead of the role, so they lie the moment the value changes; and hundreds of one-off component tokens appear that nobody can maintain. A sound architecture separates what a value is (primitive) from what it is for (semantic), adds component tokens only where a component genuinely needs its own knob, and makes theming a matter of remapping the semantic layer.

Design the token architecture.

Only if [PLATFORMS] is given: Platforms: [PLATFORMS]. Themes: light, dark. If no platforms were given, assume web plus a design tool, and say so.

1. Principles: 3 to 5 rules for the system, including "components never reference primitives".
2. Naming: define the grammar, for example {category}.{concept}.{variant}.{state} for semantic tokens (color.text.secondary, color.bg.danger.hover) and {category}.{hue or scale}.{step} for primitives (color.blue.600, space.4). Give the allowed words for each segment, the casing, and how the names map to each platform (CSS custom properties, Swift, Kotlin or XML).
3. Primitive tokens: colour ramps derived from the brand inputs (10 to 12 steps per hue, built in a perceptual space such as OKLCH so steps look even; list the target lightness per step and mark hand-converted hex values as approximate, to be regenerated by a colour tool), neutrals, spacing scale (a 4 px base is common), radii, border widths, type families, sizes, weights and line heights, shadows or elevation, and motion durations and easings. Give values.
4. Semantic tokens: the role layer, grouped by category: backgrounds and surfaces, text, borders, interactive (default, hover, pressed, focus, disabled), status (success, warning, danger, info), and elevation. Show the value for each theme as a reference to a primitive.
5. Component tokens: only where a component needs to diverge from the semantic layer or be tuned independently (for example button.primary.bg), with the rule for when one may be added.
6. Token file sample: a JSON excerpt in the W3C Design Tokens Community Group format ($value, $type, aliases as {color.blue.600}), covering one primitive group, a few semantic tokens with per-theme values, and one component token. Show how themes are expressed (separate files or sets per theme).
7. Theming rules: how each theme in light, dark remaps the semantic layer; for dark themes, use lighter surfaces for higher elevation instead of shadows, avoid pure black and pure white body text, and re-check contrast. State that every text-on-background semantic pair must meet 4.5:1 (3:1 for large text and UI) in every theme, and list the pairs to verify.
8. Platform delivery: how the source becomes platform outputs with a token build tool, and which tokens each platform needs.
9. Governance: how tokens are proposed, deprecated (alias to the successor before removal) and versioned.
10. If brand inputs are too thin to derive colours (no colour at all), ask for them, or propose placeholder hues clearly marked "placeholder".

• Do not claim contrast ratios you have not computed. Mark pairs "to verify" unless you show the calculation.
• Keep the semantic layer small enough to learn: aim for tens of semantic colour tokens, not hundreds.
• Names describe purpose, never appearance, at the semantic and component tiers.
• Separate what you verified from what you inferred. Mark inferences as such.
• When you do not know, say "I don't know" once and state what would settle it.

Markdown with the contract's sections in order. Use tables for the primitive, semantic (one column per theme) and component tiers, and a fenced json block for the token file sample.