design-system-governance

Enforce CSS token and CVA variant consistency across JoyJoin web and mini-program UI components.

Updated Dec 24, 2025
One-click install
npx skills add https://github.com/JoyJoin-Tech-Limited/JoyJoin_app_v0.1 --skill design-system-governance-joyjoin-tech-limited
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: design-system-governance
Source: https://github.com/JoyJoin-Tech-Limited/JoyJoin_app_v0.1/tree/main/.github/skills/design-system-governance
Command: npx skills add https://github.com/JoyJoin-Tech-Limited/JoyJoin_app_v0.1 --skill design-system-governance-joyjoin-tech-limited

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? UI components drift into inconsistency when developers add ad-hoc hex values, inline style overrides, or one-off styled buttons instead of using shared design tokens and variants. This Skill provides the rules, token tables, and review checklists needed to keep JoyJoin's web and mini-program interfaces visually consistent and accessible. ## Core Features & Use Cases - Token governance: Defines where CSS custom properties live (index.css :root and .dark blocks) and how to add new tokens for both light and dark modes. - CVA variant management: Standardizes button variants (default, secondary, outline, ghost, destructive) in packages/shared/src/ui/buttonVariants.ts instead of inline Tailwind overrides. - Accessibility and exception discipline: Enforces WCAG AA contrast, 44px touch targets, visible --ring focus indicators, and documented visual exceptions with rationale comments. - Use Case: When asked to add a warning button variant, the Skill directs you to extend the shared CVA config, define tokens in both apps' index.css light and dark blocks, and verify both app builds. ## Quick Start Ask the assistant to review a component for token usage or to add a new button variant following the design system governance rules.

Frequently Asked Questions about design-system-governance

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a new button variant with CVA?▼

Add the variant to packages/shared/src/ui/buttonVariants.ts using class-variance-authority, then define any new tokens in both apps' index.css :root and .dark blocks. Run both app builds to confirm no regressions.

How do I add a new CSS design token for light and dark mode?▼

Define the token in the consuming app's index.css inside both the :root and .dark blocks, never inline in components. Document the design intent and verify the component renders correctly in both modes.

Can I use a hard-coded hex colour in a component?▼

No. Replace hard-coded hex values with the nearest brand token such as --btn-primary-gradient. If a genuine exception exists, add a code comment with the format Exception: followed by the rationale.

Why does my component look broken in dark mode after adding a token?▼

The token was added to :root but not to the .dark block in index.css. Add the dark-mode value in both apps' stylesheets so the variable resolves under the .dark class.

What accessibility requirements apply to buttons in this design system?▼

Primary CTAs need at least 44px touch targets, icon buttons need aria-label, focus rings must use the --ring token, and gradient fills must meet WCAG AA 4.5:1 contrast. Loading states set aria-busy and disabled.

When should I not use this design token workflow?▼

Do not use it for component placement or layout composition decisions, brand narrative or logo usage questions, or backend logic. Those belong to frontend architecture, brand guidelines, or server-side workflows respectively.