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.

Design philosophy

Mémoire's visual language draws from terminal precision, blank architectural surfaces, and rose-sunset atmosphere. Monospace fonts handle data and system labels. Serif italic adds editorial warmth. Rose and soft sunset tones appear as a controlled floral signal layer over black and white.

The system is deliberately sparse. Every element must earn its pixels - no decorative borders, no gratuitous shadows, no animation without purpose. This restraint is the design decision, not a limitation. When an interface is 90% negative space and typography, every remaining element carries maximum weight.

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. The default palette is blank white, black, and rose-sunset accents.

Token categories

Rose sunset base tokens

The default Mémoire aesthetic is now blank white architectural surfaces with a black and rose-sunset accent system. Reading surfaces stay quiet; rose marks action, focus, selection, and atmosphere.

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

Floral, but technical

Mémoire uses blank white surfaces and a deep black base, then reserves rose and sunset warmth for action, focus, selection, hero atmosphere, and high-value moments. The gradient is a brand atmosphere, not a default fill.

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 with cubic-bezier(0.4, 0, 0.2, 1) easing. No spring physics, no bounces - direct, fast, and honest feedback. Every interactive element has three states: rest, hover, active.

State transitions

Navigation patterns

Feedback patterns

Glassmorphism

The frosted glass effect is used sparingly on elevated surfaces: nav bar, card backgrounds, and mobile overlays. It uses backdrop-filter: blur(20px) saturate(1.6) with semi-transparent white backgrounds.

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. Light-first, monospace-native, tight spacing, and token-only color.

Voice (from SOUL.md)

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

Visual language

• Light-first - off-white canvas, deep text, night panels when focus is needed
• Monospace typography as primary - JetBrains Mono, SF Mono, Fira Code
• Rose accent system - rose for action, floral pink for creative selection, sunset warmth for atmosphere
• 2px 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 arbitrary gradients - use only the liquid sunset tokens or data-driven gradients
• No rounded-full - except true pills and status chips
• 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 light-mode 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 rose system case study
{
  "color.bg": "var(--color-surface)",
  "color.fg": "var(--color-foreground)",
  "color.accent": "var(--color-accent)",
  "color.muted": "var(--color-foreground-muted)",
  "typography.family.mono": "'IBM Plex Mono', monospace",
  "radius.md": "var(--radius-md)",
  "shadow.md": "var(--shadow-md)"
}

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