Skip to main content
PerfectPalette
PerfectPalette HelpDesign System
Back to app

Design System

The Design System workflow turns your palette into a complete design.md spec you can hand to AI coding tools (Claude, Cursor, Copilot) or drop into your design handoff.

It picks up where your palette leaves off, layering typography, spacing, components, and guardrails on top of your colors — then exports everything as a single deterministic Markdown file.

The Design System stages live in the Design System section at the bottom of the journey rail in /perfect, alongside the Palette (Free) and Color System (Plus) sections. Pro users navigate directly into each stage; Free, Plus, and unauthenticated visitors see a stage-specific blurred preview with an upgrade CTA.

Pro plan only

Design System authoring is a Pro feature. Your Pro subscription unlocks:

  • Unlimited design specs per palette
  • Typography, spacing, component, and iconography workflows
  • Guardrails editor with accessibility profiles
  • design.md export with versioned snapshots

You can preview the workflow on the free plan, but saving a spec or exporting requires Pro.

The nine steps

A design spec is built in nine layered steps. You can revisit any step at any time — later steps reflect earlier choices automatically.

1. Intent

The Intent step is where you define the full design.md contract: Product Overview, Design Intent, and Design Principles. It is seeded from the answers you gave in the Plan step of the palette workflow (project type and brand attributes) and asks you to build out the rest.

Three cards:

  • Product Overview — brand or product name, project type, audience, and brand attributes. The brand name, project type, and attributes are prefilled from Plan; edit or refine them here. The brand name (optional) appears at the top of your design.md Product Overview so the spec identifies exactly what it describes.
  • Design Intent — tone notes (1–3 sentences on the voice and mood of the product) and anti-patterns (short phrases naming things the design should avoid).
  • Design Principles — a short, ordered list of actionable statements that guide every downstream decision (e.g. "Clarity over cleverness", "Every screen has one primary action"). This list cannot be captured in the Plan step, which is why Intent exists.

Each of the three sections also has a Browse library button that opens a curated, categorized picker — Brand Attributes, Anti-patterns, and Design Principles — drawn from classic UX canon, modern craft writing, and PerfectPalette's own brand guidelines. Tap to add or remove; you can still type your own custom values alongside library picks.

Each card has a Clean up with AI button. Paste rough notes, click the button, and a preview shows how the AI would rewrite your input into the structured form the design.md exporter expects. Nothing is saved until you review the preview and click Accept.

Saving the Intent step for the first time marks the spec as user-owned — the rail updates to show Intent as complete and the rest of the Design System knows you have filled in the full contract, not just the onboarding seed from Plan.

2. Palette

Your generated palette becomes the color section of the spec. Palette Health is tracked as one of the three layered scores on your design-system overview.

3. Typography

Choose primary and secondary font families from a curated catalog, map families to roles (display, body, mono), and pick a type scale preset (minor third, major third, perfect fourth, etc.). Providers include Google Fonts, Adobe Fonts, and system stacks.

4. Spacing & Surfaces

Set your base unit (usually 4px or 8px), step scale, density, and surface treatments — radius, border style, and shadow scale. Surface tokens map to cards, inputs, and overlays.

5. Components

Pick a component preset (Calm & Professional, Bold & Energetic, Minimal & Premium, or Friendly & Approachable) to get opinionated defaults across all component families. Override per-family with button radius and card treatment choices.

The preview covers 15 component families grouped into four sections:

  • Forms — Buttons, Cards, Inputs, More Fields (select, textarea, checkboxes, radio, toggle)
  • Data — Lists & Tables, Charts (bar and pie with your palette colors)
  • Feedback — Alerts, Toasts, Modals, Badges, Avatars, Progress, Tooltips
  • Navigation — Navigation, Tabs & Breadcrumbs

Each family preview respects your chosen preset and any overrides. Click a family in the nav to see its override controls — radius, style, density, emphasis, and other properties specific to that family. Follow preset resets a family back to the preset default.

The composite panel on the right shows all families together so you can see how they interact.

6. Iconography

Choose an icon library (Lucide, Heroicons, Material Symbols, Phosphor, and more), configure the style and stroke weight, set a size scale, and define usage rules — label pairing, touch targets, and decorative icon policy. The preview panel shows sample icons at every size token and in UI context.

7. Guardrails

Your do/don't rules and accessibility profile. WCAG AA or AAA, casing rules for labels and headings, and plain-English do's and don'ts — auto-suggested from your design intent.

Two generation paths are available:

  • Industry starter pack — pick a preset for your industry (healthcare, fintech, e-commerce, SaaS, education, legal, developer tools, or consumer social). The matching pack is auto-selected from your design intent's industry field. Click Apply pack to preview the seeded rules before merging.
  • AI refine (Pro) — type freeform instructions ("make these less corporate", "add checkout-specific dos") and click Generate suggestions. The AI rewrites your notes into clean, actionable items and removes any that already exist in your list. Preview before accepting.

8. Preview

See your entire design system in action. A realistic mock product page — nav bar, hero, KPI row, chart, data table, form, alert row, and footer — rendered using your actual palette colors, typography roles, spacing tokens, and component rules. Content adapts to your industry (healthcare, SaaS, fintech, etc.) based on the industry field in your design intent. This is the "does it feel right?" moment before you export. Pro users get the full live preview; Free and Plus users see a teaser with an upgrade prompt.

9. Export

Generate, preview, copy, and download your design.md. Save versioned snapshots so you can track how the spec evolves.

The Export page also surfaces Framework Config Files — one-click downloads for Tailwind v3 ({slug}-tailwind.config.js) and Tailwind v4 ({slug}-tailwind-v4.css). These configs are pre-populated with your palette colors plus any typography, spacing, and surface tokens you've completed. Sections appear in the file only when the corresponding workflow step is done — a spec with only colors and typography produces a config with colors and fontFamily/fontSize; adding spacing appends the spacing scale; adding surfaces appends borderRadius, boxShadow, and borderWidth.

What design.md looks like

The export follows a canonical section order so AI tools and teammates always know where to look:

## Project
## Design Intent
## Palette
## Typography
## Spacing
## Surfaces
## Components
## Iconography
## Guardrails
## Accessibility

Every section is deterministic — the same spec always produces the same Markdown.

Three scores explained

The overview page shows three layered scores:

  • Palette Health — Are your colors coherent, accessible, and well-balanced? This is the v3 Palette Quality score from your palette.
  • Design System — Does the broader system hang together? Typography, spacing, and components are checked for coherence against your palette and intent.
  • design.md Readiness — Is the spec complete enough to export? Tracks which of the nine sections are filled in.

Aim for all three in the "Ready to export" band before handing the file off.

Tips

  • Revisit anytime. All steps are editable. Your export always reflects the current state of the spec.
  • Exports are versioned. Save a snapshot at each milestone — you can see the history on the Export screen.
  • The spec is deterministic. Identical inputs always produce identical Markdown, so your export is safe to check into git.
  • Suggestions are starting points. The guardrails editor auto-suggests rules from your design intent, but you should edit them for your actual product voice.
  • Industry packs work without Pro. The deterministic industry starter packs are available on all plans. AI refine requires Pro.