DNA: Design Nexus Architecture

A theme system specification for AI-assisted development workflows. DNA provides standardized tokens, component schemas, and theme structures that enable portable, customizable design systems.

Overview

DNA is the factory standard for building themes. It defines:

• Two-tier token system — Brand → Semantic
• Component pattern — .tsx + .meta.ts (.schema.json generated from meta)
• Tailwind v4 native — Uses @theme blocks for CSS custom properties

┌─────────────────────────────────────────────────────────────┐
│                    DNA (The Standard)                       │
│                                                             │
│   Defines how themes are structured, how tokens are named,  │
│   how components are organized.                             │
│                                                             │
└─────────────────────────────────────────────────────────────┘
                            │
            implements the standard
                            │
              ┌─────────────────┼─────────────────┐
              ▼                 ▼
       ┌─────────────┐   ┌─────────────┐
       │ @rdna/      │   │ @rdna/      │
       │ radiants    │   │ your-theme  │
       │             │   │             │
       │ Retro pixel │   │ Your brand  │
       │ aesthetic   │   │ here        │
       └─────────────┘   └─────────────┘

Repository Structure

dna/
├── packages/
│   ├── radiants/                  # @rdna/radiants — Reference theme
│   │   ├── tokens.css             # Design tokens (oklch, @theme block)
│   │   ├── dark.css               # Dark mode overrides (.dark class)
│   │   ├── typography.css         # Element styles
│   │   ├── fonts.css              # @font-face declarations
│   │   ├── components/core/       # UI components with meta + generated schemas
│   │   ├── generated/figma/       # Generated DTCG tokens + component contracts for Figma/agents
│   │   └── registry/              # Runtime registry, prop controls, showcase hooks
│   │
│   └── preview/                   # @rdna/preview — Shared PreviewPage component
│
├── tools/
│   └── playground/                # Component playground + agent workflow surface
│
├── apps/
│   └── rad-os/                    # RadOS desktop-OS showcase (Next.js 16)
│
├── docs/
│   ├── theme-spec.md              # Full specification (v1.0.0)
│   ├── plans/                     # Current implementation plans
│   ├── research/                  # Current research + reusable prompt docs
│   └── solutions/                 # Integration patterns + tooling guides
│
├── archive/                       # Implemented / historical docs, plans, prompts
│
├── ideas/                         # Future explorations
└── CLAUDE.md                      # AI assistant instructions

Theme Packages

Package	Components	Schemas	Status
@rdna/radiants	See components/core/	Full meta + schema pattern	Reference implementation

Token System

DNA uses a two-tier semantic token system:

/* All tokens in a single @theme block (Tailwind v4 requirement) */
@theme {
  /* Tier 1: Brand Tokens — raw oklch palette */
  --color-ink: oklch(0.13 0.02 75);
  --color-cream: oklch(0.97 0.04 95);
  --color-mint: oklch(0.92 0.1 145);

  /* Tier 2: Semantic Tokens — components use these */
  --color-page: var(--color-cream);
  --color-inv: var(--color-ink);
  --color-main: var(--color-ink);
  --color-flip: var(--color-cream);
  --color-line: var(--color-ink);
  --color-accent: var(--color-mint);
}

Required Semantic Tokens

Every DNA theme must define:

Category	Tokens
Surface	page, inv
Content	main, flip
Edge	line

Recommended Tokens

Category	Tokens
Surface	tinted, card, depth
Content	sub, mute, link
Edge	edge-secondary, rule, focus
Action	accent, accent-inv, danger
Status	success, warning, danger, link
Motion	duration-fast, duration-base, duration-slow, easing-default

Component Pattern

Each component has an implementation and a meta file (schema is generated):

Button/
├── Button.tsx           # React implementation
├── Button.meta.ts       # Metadata, token bindings, registry config
└── Button.schema.json   # Generated from meta — prop types for AI tools

Schema File (AI Interface, generated from meta)

{
  "name": "Button",
  "description": "Primary action trigger",
  "props": {
    "variant": {
      "type": "enum",
      "values": ["primary", "secondary", "ghost"],
      "default": "primary"
    },
    "size": {
      "type": "enum",
      "values": ["sm", "md", "lg"],
      "default": "md"
    }
  },
  "slots": ["icon", "children"],
  "examples": [
    { "props": { "variant": "primary" }, "children": "Click me" }
  ]
}

Styling Rules

// DO: Use semantic tokens
className="bg-page text-main border-line"

// DON'T: Hardcode colors
className="bg-[#FEF8E2] text-[#0F0E0C]"

// DO: Use token-based shadows
className="shadow-[2px_2px_0_0_var(--color-line)]"

// DON'T: Hardcoded shadow colors
className="shadow-[2px_2px_0_0_#000]"

Dark Mode

The DNA spec supports class, data-attribute, or media-query activation. The reference theme (@rdna/radiants) uses .dark class only:

.dark {
  --color-page: var(--color-ink);
  --color-main: var(--color-cream);
  /* Surface/content/edge tokens invert; action/status tokens stay the same */
}

Converting Existing Projects

The historical DNA conversion prompt set now lives in archive/prompts/dna-conversion/ and is kept as an unmaintained reference:

1. Phase 0: Assessment — Scan codebase for tokens and components
2. Sprint Generator — Create task breakdown
3. Templates — Token foundation, component schemas, refactoring, dark mode

See archive/conversion/dna-conversion.md for the archived guide.

Integration

• Claude Code / Cursor — AI assistants that use schemas for context
• @base-ui/react — Headless primitive layer for all interactive components
• json-render — Planned runtime format for AI-generated UI (not yet integrated)

Figma Contracts

Radiants can now generate Figma-ready token and component contract artifacts directly from the authored CSS tokens and *.meta.ts files.

pnpm registry:generate

That command now refreshes:

• packages/radiants/generated/figma/primitive/*.tokens.json
• packages/radiants/generated/figma/semantic/semantic.tokens.json
• packages/radiants/generated/figma/contracts/*.contract.json
• .component-contracts.example

Agent Quick Start

1. Run pnpm registry:generate.
2. Copy .component-contracts.example to .component-contracts.
3. Fill in FIGMA_ACCESS_TOKEN and FIGMA_FILE_KEY.
4. Point token-sync agents at TOKENS_DIR=packages/radiants/generated/figma.
5. Point component-generation agents at CONTRACTS_DIR=packages/radiants/generated/figma/contracts.

In this repo, the local Figma skills already expect that layout:

• .claude/skills/cc-figma-tokens/SKILL.md reads TOKENS_DIR
• .claude/skills/cc-figma-component/SKILL.md reads CONTRACTS_DIR
• .claude/skills/sync-figma-token/SKILL.md can diff the generated token JSON against Figma variables

Key Decisions

Area	Choice
CSS	Tailwind v4 native (@theme blocks)
Token naming	surface-*, content-*, edge-*, action-*, status-*
Components	Copy-on-import (like shadcn)
Color modes	Light + Dark only (v1)
Motion	CSS-first, ease-out only, max 300ms
Icons	Custom dual-size sets: 16px pixel-art + 24px detailed

Documentation

• Theme Specification — Complete v1.0.0 spec
• Archived Conversion Guide — Historical migration reference
• CLAUDE.md — AI assistant instructions

License

MIT