Define reusable tokens with ak:design-system

Use ak:design-system to formalize visual decisions as primitive, semantic, and component tokens. The Skill also includes component state references, Tailwind mapping guidance, token-generation and validation helpers, and a separate token-driven slide system.

Choose ak:design-system for a reusable contract

Use ak:design-system when

• You need token JSON, CSS variables, naming rules, scales, or theme aliases.
• You need component variants and states documented for design-to-code handoff.
• You want to inspect source for hardcoded values that should use tokens.
• You need an HTML slide artifact driven by an approved token source.

Choose another workflow when

• You need broad UI/UX recommendations before defining the system. Use ak:ui-ux-pro-max.
• You need to implement a page or component against an existing system. Use ak:frontend-design.
• You need a findings-only audit against current web guidelines. Use ak:web-design-guidelines.
• You need a campaign visual rather than a reusable UI contract. Use ak:design.

Prepare the source of truth and runtime

Provide the current brand guide, existing variables or token files, supported themes, component inventory, target stack, accessibility requirements, and the exact files that may change. Decide whether the run is advisory, generates new files, validates existing code, or builds slides.

Complete Onboarding and review Runtime adapters.

Run the Skill

/ak:design-system Audit ./src/styles and the supplied brand guide. Propose primitive, semantic, and button/input component tokens with light and dark mappings. Do not write files yet

/ak:design-system Audit ./src/styles and the supplied brand guide. Propose primitive, semantic, and button/input component tokens with light and dark mappings. Do not write files yet

$ak:design-system Audit ./src/styles and the supplied brand guide. Propose primitive, semantic, and button/input component tokens with light and dark mappings. Do not write files yet

After approval, authorize exact outputs, for example tokens.json and tokens.css, plus the source directory to validate. The packaged generator uses --config or -c for input, --output or -o for a file, and --format or -f with css or tailwind. Without --output, it prints to standard output.

The validator requires --dir or -d. Its --fix option shows suggested fixes; it does not apply them. These are helper-script options, not Skill flags.

Understand the stages

1. Inventory the current system. The workflow reads approved brand values, existing tokens, themes, component states, and stack conventions.
2. Define the layers. Primitives hold raw values, semantic tokens assign purpose, and component tokens map purpose to component properties and states.
3. Review names and mappings. You approve theme behavior, accessibility intent, state coverage, and migration boundaries before files change.
4. Generate approved output. The helper can transform a JSON token config into CSS or Tailwind-oriented output and create parent directories for the selected output file.
5. Validate usage. The validator scans the chosen directory for hardcoded color and size patterns and returns locations plus suggestions.
6. Verify the implementation. Relevant theme, contrast, state, component, and repository checks run against the resulting files.

For slide work, keep narrative and data approval separate. The slide helpers can use bundled decision tables, token validation, Chart.js, and optional background resources; they do not establish that the story or numbers are true.

Keep mutations and external resources explicit

Do not let a validation warning trigger automatic bulk replacement. Preserve user-defined values, third-party styles, generated files, and unrelated work until their ownership and intended mapping are clear.

Verify the outputs and evidence

A complete run should provide the layered token map, component/state specs, exact created or changed files, generator input and format, validator findings, and focused theme and accessibility evidence. For slides, also require the HTML path, data sources, token-validation result, keyboard/navigation check, and responsive visual review.

Contrast guidance and ARIA examples in the references are requirements to test, not proof that generated components or slides meet them.

Troubleshoot or continue

Continue with the Marketing Kit overview or Projects, artifacts, and checkpoints.

Know the current limits

• Stable and beta contain byte-identical ak:design-system content in the inspected releases.
• The starter tokens and component specs are examples, not the project's brand or accessibility truth.
• The validator is pattern-based. It can miss indirect values and flag valid exceptions; it is not a browser, type checker, or accessibility engine.
• The slide knowledge is bundled release content, not current evidence about an audience, market, platform, library, or hosted image.
• A generated token file does not update every consumer automatically unless separately approved implementation work changes those consumers.