mémoire design system

The foundational layer that powers every Mémoire-generated interface. Tokens, primitives, components, and patterns — all built for autonomous reskinning while preserving developmental integrity.

The semantic layer

Tokens are the single source of truth for all visual decisions. Mémoire extracts them from Figma variables and exports as CSS custom properties, Tailwind config, or raw JSON. Every generated component references tokens — never raw values.

Token categories

AgenticUI base tokens

The default Mémoire aesthetic — dark-first, monospace-native. These are the exact tokens from the dashboard and preview system.

Atomic level badges

Each atomic level has a fixed color used across the dashboard, preview, and generated documentation.

shadcn token mapping

Figma tokens are auto-mapped to shadcn CSS variables via regex in tailwind-tokens.ts. Values are converted to HSL for shadcn compatibility.

Export formats

# Export as CSS custom properties
memi tokens --format css

# Export as Tailwind config
memi tokens --format tailwind

# Export as raw JSON
memi tokens --format json

Two faces, one system

Mémoire uses a deliberate dual-font pairing. The monospace stack — SF Mono, Fira Code, JetBrains Mono — for all interface text: data, labels, code, navigation. Cormorant Garamond for display moments only: titles, brand, editorial.

CSS variables

Scale

Restrained by design

AgenticUI is dark-first and near-monochrome. Color enters only through semantic tokens (badge levels, status indicators) and data visualization. No gradients unless data-driven. No color without semantic meaning.

4px base unit

All spacing derives from a 4px base. Components use semantic spacing tokens rather than raw pixel values. Grid layouts use CSS Grid with named areas for template-level composition.

Grid system

Primitives — components/ui/

The smallest building blocks. Atoms map directly to shadcn/ui primitives. The auto-spec engine infers atomic level from component names via regex pattern matching in auto-spec.ts. All 21 shadcn components are mapped in shadcn-mapper.ts.

shadcn/ui component map (21)

Full shadcn map from SHADCN_IMPORTS in the codegen engine:

Auto-inference patterns

The auto-spec engine infers atomic level from Figma component names. These regex patterns are in auto-spec.ts:

Composed primitives — components/molecules/

Molecules combine 2–5 atoms into a functional unit. They map to auto-spec patterns like form-field, stat, metric, card. Output goes to components/molecules/.

{
  "name": "MetricCard",
  "type": "component",
  "level": "molecule",
  "purpose": "Display a single KPI metric with title, value, and optional trend indicator",
  "variants": ["default", "compact", "highlighted"],
  "props": {
    "title": "string",
    "value": "string",
    "change": "string?",
    "trend": "up | down | flat"
  },
  "shadcnBase": ["Card", "Badge"],
  "accessibility": {
    "role": "article",
    "ariaLabel": "required",
    "keyboardNav": false
  },
  "tags": ["dashboard", "kpi"]
}

Stateful composites — components/organisms/

Organisms are complex components with real state and behavior. They compose molecules and atoms, handle data fetching, and manage interaction flows. This is where business logic lives in the component tree.

Layout skeletons — components/templates/

Templates define page structure without content. They specify grid areas, responsive breakpoints, and slot positions. Content is injected by page specs — templates are purely structural.

Five specs, one system

Every artifact in Mémoire starts as a typed JSON spec validated by Zod. The spec is the single source of truth — code generation, validation, and preview all derive from it. Defined in src/specs/types.ts.

ComponentSpec fields

Output folders

Figma to code mapping

Every ComponentSpec has a codeConnect field that maps Figma components to codebase files. When Figma MCP returns Code Connect snippets, the codegen engine uses the mapped component directly instead of generating from scratch.

{
  "codeConnect": {
    "figmaNodeId": "123:456",
    "codebasePath": "src/components/ui/button.tsx",
    "props": {
      "variant": "variant",
      "size": "size"
    },
    "mapped": true
  }
}

Repeatable structures

PageSpec defines six layout types. These map to CSS Grid structures that templates implement. Section-level layouts control card placement within each page section.

Page layouts (PageSpec.layout)

Section layouts (SectionSchema.layout)

Responsive defaults (PageSpec.responsive)

Motion and state

Interactions are minimal and purposeful. Transitions use 150–200ms durations. No spring physics, no bounces — direct, fast, and honest feedback.

Visualizing system state

Mémoire generates dataviz from DataVizSpec using Recharts by default (also supports d3, visx, custom). Each chart is wrapped in a shadcn Card. Interactions and accessibility are defined in the spec.

Chart types (DataVizSpec.chartType)

Chart interactions

The autonomous design engine

AgenticUI is defined by .memoire/SOUL.md — the design soul file. It is not a brand, it is a structural foundation any brand can sit on. Dark-first (#111113), monospace-native, 4px radius, tight spacing.

Voice (from SOUL.md)

• Minimal, precise, monospace-native — no marketing speak, no filler
• Technical but warm — like good documentation

Visual language

• Dark-first — bg: #111113, fg: #ffffff
• Monospace typography as primary — SF Mono, Fira Code, JetBrains Mono
• Muted accents, high contrast text — #a0a0a6 accent, #636369 muted
• 4px radius, tight spacing — no decorative elements, every pixel earns its place

Interaction principles

• Immediate feedback — on all actions, no loading spinners without progress
• Keyboard-first, mouse-friendly — every action has a keyboard path
• Progressive disclosure — show less, reveal on demand
• Respect prefers-reduced-motion — honor system accessibility settings

Anti-patterns (enforced)

• No gradients — unless data-driven (heatmaps, charts)
• No rounded-full — on containers. 4px max radius
• No color without semantic meaning — decoration is noise
• No animation > 400ms — for UI transitions (cinematic excepted)

How Claude uses it

Claude reads SOUL.md + the token system, applies defaults, and outputs shadcn/ui + Tailwind. The self-healing loop (CREATE → SCREENSHOT → ANALYZE → FIX → VERIFY, max 3 rounds) validates the result against the aesthetic.

"use client"

import * as React from "react"
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card"
import { Badge } from "@/components/ui/badge"
import { cn } from "@/lib/utils"

export type MetricCardVariant = "default" | "compact" | "highlighted"

export interface MetricCardProps extends React.HTMLAttributes<HTMLDivElement> {
  title: string
  value: string
  change?: string
  trend: "up" | "down" | "flat"
  variant?: MetricCardVariant
}

export function MetricCard({ title, value, change, trend, variant = "default", className, ...props }: MetricCardProps) {
  return (
    <Card className={cn("transition-all", className)} {...props}>
      <CardHeader>
        <CardTitle>{title}</CardTitle>
      </CardHeader>
      <CardContent>
        <div className="text-2xl font-bold">{value}</div>
        {change && <span className="text-sm text-muted-foreground">{change}</span>}
        {trend && <Badge>{trend}</Badge>}
      </CardContent>
    </Card>
  )
}

One structure, any brand

Reskinning is how Mémoire transforms a neutral AgenticUI project into a branded case study. The structure stays, the skin changes. This is done entirely through token overrides — no component code changes.

What changes (token categories from DesignToken)

What stays

// Override tokens for a fintech case study
{
  "color.bg": "#0d1117",
  "color.fg": "#e6edf3",
  "color.accent": "#58a6ff",
  "color.muted": "#8b949e",
  "typography.family.mono": "'IBM Plex Mono', monospace",
  "radius.md": "8px",
  "shadow.md": "0 4px 24px rgba(0,0,0,0.3)"
}

Presentable by default

Every Mémoire project generates a preview gallery automatically via memi preview. It runs on port 3030 and serves 6 pages in the AgenticUI aesthetic or the project's reskinned version.

Preview gallery pages

• Index — project overview with component counts, token summary, Figma status
• Specs — all component, page, and dataviz specs with validation status
• Design System — live token table with swatches and export controls
• Research — ingested data visualized as charts and insight cards
• Portal — Figma bridge status, connected agents, auto-discovery
• Changelog — version history with architectural decisions documented

Workflow

Guardrails that hold

Reskinning is surface-level by design. The development architecture underneath never bends. These constraints are enforced in code — not by convention, not by documentation, but by Zod schemas and validation at every step.

Enforced constraints