Working with AI

Machine-Readable Token Manifests

Our design system exports detailed machine-readable config manifests to let AI coding agents identify correct token properties instantly:

tokens.json

Lists every foundation scale color, semantic layout role (light and dark mode mappings), easing curves, and radii configurations.

components.json

Maps all components, visual props, allowed variant keys, type interfaces, and default variables.

Lint Rules & Verification Pipelines

AI agents must conform to strict styling constraints. The following validation tasks run automatically in CI:

npm run lint:tokens — Checks for hardcoded hex colors or foundation variables inside layout files.npm run lint:classes — Audits tailwind classes to ensure they use allowed semantic tokens list.npm run manifest:check — Checks if the components.json manifest is synchronized with the components.

Instruction Prompts

When prompting an AI coding assistant to create layouts using Shavin, use the following context guideline template:

You are building pages using the Shavin UI design system.
Follow these constraints:
1. Use semantic tailwind classes (like bg-canvas, text-fg) rather than raw styles.
2. Nest content inside Card, Flex, and Grid elements to control margins.
3. Import components directly from "@shavin/ui" rather than deep files.

Linter warning: AI assistants must regenerate manifests after adding or modifying components by executing: npm run manifest:gen.