/standardize-ui-with-design-tokens

When to use it

The skill is meant to be pulled in when one of these conditions is true.

• A product has repeated colours, spacing, type, radii, borders, or shadows.
• Components look similar but should not inherit from each other semantically.
• Theme work, redesign work, or accessibility work risks changing unrelated surfaces.
• Engineers need a clear rule for when to use primitives, semantic tokens, or component tokens.

Start by asking

These questions keep the work from jumping straight to implementation details.

• What decisions are true primitives, and what decisions describe a product role?
• Which components need their own tokens because they own their states?
• Where are values duplicated because the right token does not exist yet?
• How do light mode, dark mode, contrast, focus, and disabled states resolve?
• How will drift be detected when someone adds a new colour or spacing value?

Universal principal-level checks

Every skill should carry these concerns, even when the immediate request sounds narrower.

Skill-specific considerations

Process

Deliver

• A token hierarchy with primitive, semantic, and component-owned layers.
• Ownership rules for adding, changing, and deleting tokens.
• A drift-detection or review strategy.
• Examples showing correct and incorrect token use.

Failure modes

These are the quiet ways the work can look finished while still being risky.

• A shared token becomes a hidden dependency between unrelated components.
• Dark mode is patched with local overrides instead of resolved by the token system.
• Focus, active, disabled, and destructive states drift because they are not named.

Avoid

• Using a card token as the baseline for a button.
• Adding arbitrary values because the existing token set is hard to understand.
• Treating design tokens as only colour variables.

Verify before finishing

• Can a new component be themed without borrowing another component token?
• Can a reviewer tell why each component token exists?
• Do light mode, dark mode, focus, disabled, and destructive states pass contrast expectations?

Prompt to copy

Paste this into an AI session when you want the model to apply the full skill instead of giving a shallow answer.

Use this skill: /standardize-ui-with-design-tokens.
Title: Standardize UI with design tokens

Goal: Use shared visual foundations without letting components borrow meaning from each other.

Frame: Use this skill when visual consistency needs to become a durable system. The goal is not only to make screens match, but to preserve intent as the product changes across themes, components, states, and platforms.

Universal principal-level considerations:
- Product intent
  - Name the user, operator, developer, or business outcome the work protects.
  - Separate what the system must do from how the current implementation happens to do it.
  - Identify the smallest useful improvement and the larger direction it should not block.
- Ownership and boundaries
  - Decide which layer owns policy, presentation, transport, persistence, validation, and side effects.
  - Make shared abstractions explicit about what they own and what they leave to the caller.
  - Prefer boundaries that reduce repeated decisions without hiding important context.
- Data and state integrity
  - Define the source of truth, derived state, cached state, temporary state, and persisted state.
  - Handle missing, stale, partial, conflicting, duplicated, and invalid data deliberately.
  - Keep transformations close to system boundaries so product code does not accumulate guesses.
- Security, privacy, and abuse
  - Treat external input, user-provided values, remote resources, generated output, and stored content as untrusted.
  - Avoid leaking internal identifiers, sensitive defaults, private routes, tokens, or implementation details.
  - Consider who can trigger expensive, destructive, or externally visible behavior.
- Accessibility and comprehension
  - Check semantic structure, accessible names, focus order, keyboard behavior, contrast, and reduced-motion behavior.
  - Write states and errors so a user can understand what happened and what to do next.
  - Make important information available without relying only on color, animation, hover, or layout position.
- Performance and scale
  - Identify work that runs per request, per render, per item, per file, per route, or per user action.
  - Avoid moving repeated work into a shared abstraction if that also hides expensive behavior.
  - Plan for growth in records, tenants, users, routes, generated files, and integration consumers.
- Reliability and operations
  - Design for retries, partial failure, timeouts, idempotency, rollback, reconciliation, and observability.
  - Make failures explain what broke, who is affected, and what should be inspected next.
  - Leave an audit trail for changes that affect access, content, billing, data, publishing, or public behavior.
- Testing and release
  - Test the contract, not only the implementation detail.
  - Cover role, permission, plan, device, theme, and failure-state differences when they change behavior.
  - Add preflight checks for generated files, configuration, fixtures, migrations, and runtime definitions.
- Documentation and handoff
  - Document decisions, tradeoffs, naming rules, escape hatches, and cleanup conditions.
  - Write for the next person who has to extend, debug, or remove the system.
  - Keep examples small enough to trust and realistic enough to reuse.
- Maintenance and reversibility
  - Prefer changes that can be migrated incrementally and rolled back safely.
  - Name temporary decisions and set conditions for removing them.
  - Watch for abstractions that become permanent because nobody knows what they were originally solving.

Use this when:
- A product has repeated colours, spacing, type, radii, borders, or shadows.
- Components look similar but should not inherit from each other semantically.
- Theme work, redesign work, or accessibility work risks changing unrelated surfaces.
- Engineers need a clear rule for when to use primitives, semantic tokens, or component tokens.

Start by asking:
- What decisions are true primitives, and what decisions describe a product role?
- Which components need their own tokens because they own their states?
- Where are values duplicated because the right token does not exist yet?
- How do light mode, dark mode, contrast, focus, and disabled states resolve?
- How will drift be detected when someone adds a new colour or spacing value?

Skill-specific considerations:
- Token ownership
  - Separate raw values from semantic roles and component-owned decisions.
  - Do not let one component inherit another component token because the value currently matches.
  - Keep state tokens local to the component that owns the interaction.
- Theme behavior
  - Define light and dark mode by intent, not duplicated override patches.
  - Check contrast before treating a token as reusable.
  - Make focus and disabled states first-class, not ad hoc additions.
- Governance
  - Add naming rules for primitive, semantic, and component token layers.
  - Create a drift check or review rule for one-off values.
  - Document when a new token should be created instead of reusing an approximate one.

Process:
- Map
  - Inventory existing values and group them by visual role.
  - Mark every borrowed component token and every unnamed one-off value.
- Separate
  - Create primitive scales first, then semantic aliases, then component tokens.
  - Move component state decisions into the component layer.
- Prove
  - Test theme parity, contrast, focus states, and disabled states.
  - Show at least one example where two components share a primitive without sharing meaning.

Deliver:
- A token hierarchy with primitive, semantic, and component-owned layers.
- Ownership rules for adding, changing, and deleting tokens.
- A drift-detection or review strategy.
- Examples showing correct and incorrect token use.

Watch for failure modes:
- A shared token becomes a hidden dependency between unrelated components.
- Dark mode is patched with local overrides instead of resolved by the token system.
- Focus, active, disabled, and destructive states drift because they are not named.

Avoid:
- Using a card token as the baseline for a button.
- Adding arbitrary values because the existing token set is hard to understand.
- Treating design tokens as only colour variables.

Verify before finishing:
- Can a new component be themed without borrowing another component token?
- Can a reviewer tell why each component token exists?
- Do light mode, dark mode, focus, disabled, and destructive states pass contrast expectations?