How to get polished results from AI design kits

Make it a rule that every component uses design tokens from the global system, never hardcoded colors or font sizes. Add this to your project instructions (CLAUDE.md, .cursorrules, or equivalent):

## Design system

Every component must use the global design system via semantic tokens.
Use `bg-background`, `text-foreground`, `bg-card`, `text-primary`,
`border-border`, etc. Never hardcode colors like `bg-neutral-950` or
`text-white`. Typography uses the heading and body font variables, not
literal font-family values.

Before submitting a component, verify it contains zero hardcoded color
or font values. Run a review pass if needed.

When every component draws from the same token layer, switching the design kit repaints the entire product. Without this rule, the first kit applies cleanly and every later change means hunting down hardcoded values across fifty files.

An agent building a dropdown from scratch will get it roughly working. An agent styling a Radix UI dropdown with your kit's tokens will get it accessible, keyboard-navigable, animated, and visually consistent. The interaction work is already solved, so the agent only has to apply the look.

The component libraries that work best with design kits:

• [shadcn/ui](https://ui.shadcn.com/) copies components into your project as source code. They already use CSS variables, so a design kit's tokens slot in directly. Identity Forge ships a shadcn registry that installs a kit's tokens in one command.
• [Radix UI](https://www.radix-ui.com/) provides the unstyled primitives underneath shadcn. Use it directly when you want full control over markup and styling while keeping the accessibility and interaction behavior.
• [Base UI](https://base-ui.com/) is another unstyled primitive library with a minimal API. Good when Radix's abstraction level feels heavy for your use case.

The split is the same in each case: the library owns behavior (focus management, keyboard navigation, screen reader announcements, scroll locking, portal placement) and the design kit owns the look (colors, typography, spacing, shapes, elevation). You can swap the kit without touching the components, or swap the component library without touching the kit.

Before committing to a design kit, generate a few images of what the product could look like. Image models are good at mood, composition, and color relationships. They are bad at producing a system you can build from. Use them for the first, not the second.

1. 1

   Generate mood images

   Use an image model (gpt-image-1 works well through the Codex CLI) to explore visual directions. Generate three to five options with different moods.

   Copy

   codex exec "generate an image of a SaaS dashboard with warm, earthy tones and generous whitespace"

2. 2

   Pick the direction

   Choose the image that captures what the product should feel like. You are choosing a mood, not a layout.

3. 3

   Create the kit

   Let your agent create a design kit in Identity Forge that matches the chosen direction. Or use the extraction pipeline to extract tokens from an existing reference.

4. 4

   Maintain in Identity Forge

   From here the kit is the source of truth. Refine it in Studio, version it, and export it to your agent. The image got you the direction; the kit keeps it consistent.

Image models are good at the exploration part. They are not good at producing something an agent can build from directly. An image cannot tell an agent what border-radius to use on a card. A kit can.

The most underused technique: instead of accepting the first version of a section, ask your agent to build three variations with different layouts, densities, or emphasis patterns.

Build three variations of the pricing section:
1. A compact horizontal layout with all plans visible at once
2. A card-based layout with the recommended plan highlighted
3. A comparison table with feature rows

Use the active design kit for all three. Keep each in a
separate component file so I can compare them side by side.

This costs a few extra minutes of agent time and saves the project from looking like whatever the model defaults to. The agent applies the same design kit to each variation, so all three are on-brand. You pick the one that fits the content, the audience, and the page rhythm.

None of these is hard on its own. They add up. Enforced tokens mean the kit actually controls the look. Good component primitives mean the interactions just work. A real visual reference means the mood is intentional, not accidental. And picking from three options means the layout fits the content instead of fitting the model's default. The result looks like someone made design decisions, because someone did.