Skip to content
Docs

The design system pointer

The design system pointer is how Denote records where tokens come from without owning their values. Denote captures the aesthetic direction (the feel, the references, the density) and a pointer to a token source. The actual token values (colors, spacing, typography scales, radii, shadows) live in the target environment. Claude Code resolves the pointer at build time.

Why Denote does not own tokens

Token editors and color pickers are commodity work. Every design tool has them. Every stack (Tailwind, CSS variables, Style Dictionary, Figma Tokens, shadcn's globals.css) already has its own canonical place for tokens.

If Denote owned token values, it would become another mockup tool. It would duplicate the token store that already exists in your target environment, and the two would drift apart the moment you changed either. You would then spend time keeping them in sync instead of thinking about structure.

So Denote refuses the styling game. The thinking tool stays the thinking tool. Tokens live where they already live. Denote records a pointer.

What the pointer is

The pointer is a small declaration in design/aesthetic.json. It has two parts.

Aesthetic direction. The feel. A freeform prompt ("clean and minimal, soft shadows, generous spacing, calm palette"), reference images of products whose register you admire, mood tags, and a density preference (compact, comfortable, or spacious). This is taste. It cannot be derived from entity extraction, and no structural analysis produces it.

Token source. One of three modes.

  • default tells Claude Code to use the shadcn baseline tokens unchanged. Safe starting point. No config.
  • prompt tells Claude Code to tune the shadcn defaults from the aesthetic direction at build time. You described "warm, low-contrast, serif display type"; Claude Code adjusts the shadcn baseline to match.
  • referenced tells Claude Code that you already have a token file on disk. You give Denote a relative path to it. Claude Code reads that file as the authoritative source.

Between the three modes, every common setup is covered. A new project on a default shadcn stack uses default. A project with a strong visual direction but no pre-existing tokens uses prompt. A project that already has a designed token system (a Tailwind config in a monorepo, a Style Dictionary JSON, an exported Figma file) uses referenced.

Where it lives in the app

The design system pointer is not a layer. There is no sixth canvas for styling. The pointer lives in Project Settings, reached from the gear icon in the top bar.

Project Settings contains:

  • Project name and path
  • The aesthetic direction (the freeform prompt, references moodboard, mood tags, density)
  • The token source selector (the three modes, with a path field visible when referenced is selected)
  • Output mode preference
  • Tracking opt-out
  • A link to intelligence/ for overrides

Putting the pointer in settings rather than in a layer makes the intent clear: styling is a project-level declaration, not a per-page decision.

How Claude Code uses it

When Claude Code builds, it reads design/aesthetic.json alongside the other design files.

  • The aesthetic direction informs any visual decision that the governance schema does not already pin down. Spacing rhythm, type scale, shadow weight, motion feel.
  • The token source tells Claude Code where the numeric values live.
    • default means "use what shadcn ships."
    • prompt means "adjust shadcn using the direction, at build time."
    • referenced means "open this file and read the values from there."

The result is that the direction you described and the token source you pointed at both reach the generated code. Claude Code does not invent colors. It does not improvise a type scale when one already exists on disk.

The recipe example

In the recipe portion calculator sample, the aesthetic direction reads:

Warm and unfussy. Recipe cards should feel like postcards. Generous spacing so the phone does not feel cramped in the kitchen. Serif for recipe names, clean sans-serif for instructions. Soft shadows, generous radii, cream background rather than pure white.

References: three recipe apps and one print cookbook, all cream-backgrounded, serif-display-forward.

Density: comfortable.

Token source: prompt. The sample project does not ship a pre-existing token file, so Claude Code tunes the shadcn defaults from the direction at build time: the background shifts off pure white, radii grow, a serif display family is paired with a clean sans, shadows soften.

Nothing in design/aesthetic.json names a hex value. The direction describes intent. The build resolves it.

What this means for the output

The code Claude Code generates uses the token source as its single source of truth.

  • If default, the generated code imports shadcn as normal, with unchanged globals.css.
  • If prompt, the generated code includes the tuned globals.css Claude Code wrote from the direction.
  • If referenced, the generated code imports tokens from the referenced file path.

In all three cases, there is one canonical place for tokens. Denote does not add a second one.

What the pointer does not cover

  • Component code. Buttons, inputs, cards. These are generated from the governance schema and the design system library, not from the aesthetic direction.
  • Content. Copy, sample data, labels. Content belongs in the entity model and the build plan.
  • Layout structure. Spatial arrangement belongs in the Layout layer, not the aesthetic direction.

The pointer is only about the feel and where the token values live. It stays narrow on purpose.

Where to next