--- version: alpha name: Sparkles description: Friendly developer tooling for non-engineers — a clean zinc-on-white shadcn/ui base warmed by a single fresh-green brand accent and serif Gelica display headings paired with the geometric Articulat CF sans, so the product reads approachable rather than terminal-cold. colors: # Canvas + ink background: "#ffffff" surface: "#ffffff" surface-soft: "#fafafa" surface-muted: "#f4f4f5" ink: "#252525" # zinc-950 / oklch(14.5% 0 0), warm near-black ink-secondary: "#52525c" # zinc-600 ink-muted: "#71717b" # zinc-500, muted-foreground ink-faint: "#a0a0ac" # zinc-400 placeholder # Brand accent — fresh green primary: "#54b16c" on-primary: "#ffffff" primary-soft: "#eef7f1" # tinted green surface over white # shadcn neutral roles secondary: "#f4f4f5" # zinc-100 on-secondary: "#252525" accent: "#f4f4f5" on-accent: "#252525" destructive: "#e7000b" # oklch(57.7% .245 27.325) # Lines + focus border: "#e4e4e7" # zinc-200 border-strong: "#d4d4d8" # zinc-300 ring: "#b3b3b8" # oklch(70.8% 0 0) # Neutral scale (zinc) zinc-50: "#fafafa" zinc-100: "#f4f4f5" zinc-200: "#e4e4e7" zinc-500: "#71717b" zinc-600: "#52525c" zinc-900: "#18181b" zinc-950: "#252525" typography: display-hero: fontFamily: "Gelica, Georgia, serif" fontSize: 56px fontWeight: 700 lineHeight: 1.05 letterSpacing: -1.5px display: fontFamily: "Gelica, Georgia, serif" fontSize: 40px fontWeight: 700 lineHeight: 1.10 letterSpacing: -1px section-heading: fontFamily: "Gelica, Georgia, serif" fontSize: 30px fontWeight: 600 lineHeight: 1.20 letterSpacing: -0.5px card-title: fontFamily: "Gelica, Georgia, serif" fontSize: 22px fontWeight: 600 lineHeight: 1.30 letterSpacing: -0.25px subtitle: fontFamily: "Articulat CF, system-ui, sans-serif" fontSize: 20px fontWeight: 400 lineHeight: 1.50 letterSpacing: 0px body-large: fontFamily: "Articulat CF, system-ui, sans-serif" fontSize: 18px fontWeight: 400 lineHeight: 1.60 letterSpacing: 0px body: fontFamily: "Articulat CF, system-ui, sans-serif" fontSize: 16px fontWeight: 400 lineHeight: 1.50 letterSpacing: 0px body-medium: fontFamily: "Articulat CF, system-ui, sans-serif" fontSize: 16px fontWeight: 500 lineHeight: 1.50 letterSpacing: 0px body-small: fontFamily: "Articulat CF, system-ui, sans-serif" fontSize: 14px fontWeight: 400 lineHeight: 1.45 letterSpacing: 0px button-ui: fontFamily: "Articulat CF, system-ui, sans-serif" fontSize: 14px fontWeight: 500 lineHeight: 1.00 letterSpacing: 0px caption: fontFamily: "Articulat CF, system-ui, sans-serif" fontSize: 13px fontWeight: 500 lineHeight: 1.30 letterSpacing: 0px mono: fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace" fontSize: 14px fontWeight: 400 lineHeight: 1.50 letterSpacing: 0px spacing: xs: 4px sm: 8px md: 12px lg: 16px xl: 24px 2xl: 40px 3xl: 64px 4xl: 96px rounded: none: 0px xs: 2px sm: 6px md: 8px lg: 10px xl: 14px 2xl: 16px 3xl: 24px pill: 9999px components: button-primary: backgroundColor: "{colors.primary}" textColor: "{colors.on-primary}" typography: "{typography.button-ui}" rounded: "{rounded.md}" padding: 10px 18px button-dark: backgroundColor: "{colors.ink}" textColor: "{colors.background}" typography: "{typography.button-ui}" rounded: "{rounded.md}" padding: 10px 18px button-secondary: backgroundColor: "{colors.secondary}" textColor: "{colors.on-secondary}" typography: "{typography.button-ui}" rounded: "{rounded.md}" padding: 10px 18px button-outline: backgroundColor: "{colors.background}" textColor: "{colors.ink}" typography: "{typography.button-ui}" rounded: "{rounded.md}" padding: 10px 18px borderColor: "{colors.border}" button-ghost: backgroundColor: "{colors.background}" textColor: "{colors.ink-secondary}" typography: "{typography.button-ui}" rounded: "{rounded.md}" padding: 8px 12px badge: backgroundColor: "{colors.primary-soft}" textColor: "{colors.primary}" typography: "{typography.caption}" rounded: "{rounded.pill}" padding: 2px 10px card: backgroundColor: "{colors.surface}" textColor: "{colors.ink}" rounded: "{rounded.xl}" padding: 24px borderColor: "{colors.border}" card-soft: backgroundColor: "{colors.surface-soft}" textColor: "{colors.ink}" rounded: "{rounded.xl}" padding: 24px borderColor: "{colors.border}" input: backgroundColor: "{colors.background}" textColor: "{colors.ink}" typography: "{typography.body-small}" rounded: "{rounded.md}" padding: 8px 12px borderColor: "{colors.border}" input-focus: backgroundColor: "{colors.background}" textColor: "{colors.ink}" rounded: "{rounded.md}" borderColor: "{colors.ring}" nav-bar: backgroundColor: "{colors.background}" textColor: "{colors.zinc-900}" typography: "{typography.button-ui}" padding: 16px 24px borderColor: "{colors.border}" code-block: backgroundColor: "{colors.surface-muted}" textColor: "{colors.ink}" typography: "{typography.mono}" rounded: "{rounded.md}" padding: 16px borderColor: "{colors.border}" --- # Sparkles Design System ## Overview Sparkles is "Lovable for existing projects" — a tool that lets non-engineers on a team (marketing, design, ops) open pull requests against a real codebase without writing code. Its design problem is the opposite of most developer tools: it has to feel safe and inviting to people who are intimidated by GitHub, while still signalling to the technical person who connects the repo that it's a serious engineering product. The visual system solves this by warming a strictly neutral foundation with one friendly accent and a humanist serif. The base is a clean shadcn/ui zinc-on-white theme. The canvas is pure white (`{colors.background}`), text is a warm near-black zinc (`{colors.ink}`, oklch 14.5%), and the entire neutral chrome — borders, muted surfaces, secondary buttons, code blocks — is built from the zinc scale (`{colors.zinc-100}` through `{colors.zinc-200}`). This keeps the interface quiet and screenshot-friendly, with subtle 1px `{colors.border}` lines doing the structural work rather than shadows or fills. The personality comes from two deliberate departures from the shadcn default. First, headings are set in **Gelica**, a rounded humanist serif (Georgia fallback) — an unusual choice for a dev tool that immediately softens the page and makes copy feel written-by-a-human rather than generated. Body and UI text use **Articulat CF**, a clean geometric sans, so the serif/sans contrast carries the hierarchy. Second, a single fresh green (`{colors.primary}`, `#54b16c`) is the brand accent: it appears as a solid fill behind brand marks and key moments, with a tinted `{colors.primary-soft}` for badges. Green reads as "go," "approved," "merged" — the exact emotional note a PR tool wants. **Key Characteristics:** - shadcn/ui zinc base — pure-white canvas, warm near-black `{colors.ink}`, full neutral zinc scale - One brand accent: fresh green `{colors.primary}` (`#54b16c`), used as solid fill + soft tint, never decoratively spread - Gelica humanist serif for all display/headings — the friendly, hand-written signal - Articulat CF geometric sans for body and UI — serif/sans pairing drives hierarchy - Border-first structure: 1px `{colors.border}` lines, minimal shadow, soft `{colors.surface-soft}` panels - Medium radii (8–14px) — rounded enough to feel approachable, not pill-soft - Dark `{colors.ink}` and green `{colors.primary}` both serve as primary-button fills depending on context ## Colors ### Primary - **Sparkle Green** (`{colors.primary}`): The single brand accent. Solid fill behind brand marks and key CTAs; the "approved / merged / go" note. - **Green Soft** (`{colors.primary-soft}`): Tinted green surface for badges and highlight chips over white. - **Ink** (`{colors.ink}`): Primary text and headings; warm near-black zinc, also used as a dark button fill. - **White** (`{colors.background}`): Canvas, card surfaces, text on green/dark fills. ### Text - **Ink Secondary** (`{colors.ink-secondary}`): Sub-headings, strong body copy. - **Ink Muted** (`{colors.ink-muted}`): Descriptions, captions, muted UI. - **Ink Faint** (`{colors.ink-faint}`): Placeholder text, disabled states. ### Neutral Roles (shadcn) - **Secondary** (`{colors.secondary}`): Secondary button + muted surface, zinc-100. - **Surface Soft** (`{colors.surface-soft}`): Quiet panels, alternating sections. - **Surface Muted** (`{colors.surface-muted}`): Code-block background. - **Destructive** (`{colors.destructive}`): Error/delete actions only. ### Lines & Focus - **Border** (`{colors.border}`): Default 1px hairline on cards, inputs, nav — zinc-200. - **Border Strong** (`{colors.border-strong}`): Emphasized dividers, zinc-300. - **Ring** (`{colors.ring}`): Focus ring on interactive elements. ### Neutral Scale - **Zinc 50–950** (`{colors.zinc-50}` … `{colors.zinc-950}`): The achromatic backbone for every surface, line, and muted text value. ## Typography ### Font Family - **Display / Headings**: `Gelica`, fallbacks `Georgia, serif` — a rounded humanist serif. - **Body / UI**: `Articulat CF`, fallbacks `system-ui, sans-serif` — geometric humanist sans. - **Monospace**: `ui-monospace, SFMono-Regular, Menlo, monospace` for code/diff contexts. ### Hierarchy The complete scale lives in the `typography:` token block above. Reference tokens directly (`{typography.display-hero}`, `{typography.body}`). | Token | Use | |---|---| | `display-hero` | 56px serif hero headline | | `display` | Large section openers | | `section-heading` | Feature section titles | | `card-title` | Card and feature headings | | `subtitle` | Hero subtitle, intros | | `body-large` | Lead paragraphs | | `body` | Standard reading text | | `body-medium` | Emphasized body, labels | | `body-small` | Dense UI, captions | | `button-ui` | Buttons, nav links | | `caption` | Metadata, badges | | `mono` | Code, diffs, branch names | ### Principles - **Serif heads, sans body**: Gelica carries warmth and voice at display sizes; Articulat CF keeps body and UI neutral and legible. The contrast IS the hierarchy. - **Negative tracking at scale**: Display sizes tighten letter-spacing (-1px to -1.5px); body stays at 0. - **Restrained weights**: Serif at 600–700 for heads, sans at 400 (read) / 500 (interact). No heavy sans display. ## Layout ### Spacing System The complete scale lives in the `spacing:` token block above. 8px base unit with a 4px floor; sections breathe with `{spacing.3xl}`–`{spacing.4xl}` vertical rhythm. ### Grid & Container - Max content width ~1200px, centered - Hero: centered single column with a serif headline and sans subtitle - Feature sections: 2–3 column card grids - Borders, not fills, separate regions ### Whitespace Philosophy - **Calm and roomy**: generous vertical padding keeps the page unintimidating for non-technical users. - **Accent sparingly**: green appears in concentrated moments (brand mark, primary CTA, merged-state chips), never as a wash. - **Hairline structure**: 1px `{colors.border}` lines define cards and sections; shadows stay minimal. ## Elevation & Depth | Level | Treatment | Use | |---|---|---| | Flat | No shadow | Page background, text blocks | | Hairline | 1px `{colors.border}` | Cards, inputs, nav, code blocks | | Soft panel | `{colors.surface-soft}` fill + hairline | Quiet sections, nested panels | | Lifted | Hairline + small soft shadow (`#0000001a`) | Hover/active cards | | Focus | `{colors.ring}` ring | Keyboard focus on interactive elements | **Shadow Philosophy**: Depth is mostly drawn, not lit. The system leans on 1px zinc borders and soft-gray surface tints; shadows are reserved for hover lift and overlays, kept at low opacity (`#0000001a`). ## Shapes | Token | Value | Use | |---|---|---| | `none` | 0px | Reserved | | `xs` | 2px | Tiny inline elements | | `sm` | 6px | Small chips | | `md` | 8px | Buttons, inputs | | `lg` | 10px | shadcn base radius | | `xl` | 14px | Cards | | `2xl` | 16px | Large cards | | `3xl` | 24px | Hero panels, feature blocks | | `pill` | 9999px | Badges, status pills | ## Components The full component spec lives in the `components:` token block above. Reference tokens directly (`{components.button-primary}`, `{components.card}`). ### Buttons - **`button-primary`** — green fill, white text, 8px radius. The brand CTA. - **`button-dark`** — `{colors.ink}` fill, white text. Neutral primary action. - **`button-secondary`** — zinc-100 fill, ink text. - **`button-outline`** — white with 1px `{colors.border}`. - **`button-ghost`** — text-only, used in nav. ### Badges - **`badge`** — `{colors.primary-soft}` background, green text, full pill. Status and category chips. ### Cards - **`card`** — white, 1px `{colors.border}`, 14px radius. - **`card-soft`** — `{colors.surface-soft}` fill for quiet/nested panels. ### Inputs - **`input`** — white, 1px `{colors.border}`, 8px radius. Focus swaps border to `{colors.ring}`. ### Navigation - **`nav-bar`** — white sticky header, zinc-900 ghost links, bottom hairline border. ### Code - **`code-block`** — `{colors.surface-muted}` background, mono text, 8px radius — for diffs, branch names, and snippets. ## Do's and Don'ts ### Do - Keep the chrome neutral zinc — let green be the one accent - Use Gelica serif for headings, Articulat CF sans for everything else - Structure with 1px `{colors.border}` hairlines, not heavy shadows - Use green for "go / approved / merged" moments - Use `{colors.primary-soft}` for green-tinted badges, not full-saturation backgrounds with small text ### Don't - Don't spread green as a background wash — it's a concentrated accent - Don't set headings in the sans — the serif is the brand voice - Don't replace hairline borders with drop shadows on cards - Don't put small text directly on `{colors.primary}` (use white) — keep contrast safe - Don't introduce a second accent hue — the palette is zinc + green only --- ## Responsive Behavior ### Breakpoints | Name | Width | Key Changes | |------|-------|-------------| | Mobile | <640px | Single column, stacked cards | | Tablet | 640–1024px | 2-column grids | | Desktop | 1024–1280px | Full 3-column layout | | Large | >1280px | Centered, generous margins | ### Collapsing Strategy - Hero serif headline scales down, keeps negative tracking - Nav links collapse to a menu; primary CTA persists - Feature cards: 3 → 2 → 1 column - Section vertical spacing tightens from `{spacing.4xl}` to `{spacing.2xl}` on mobile --- ## Agent Prompt Guide ### Quick Color Reference - Brand accent / primary CTA: Sparkle Green `{colors.primary}` - Neutral primary CTA: Ink `{colors.ink}` - Background: White `{colors.background}` - Heading text: Ink `{colors.ink}` in Gelica serif - Body text: Ink Muted `{colors.ink-muted}` in Articulat CF - Border: 1px `{colors.border}` ### Example Component Prompts - "Hero: white background. Headline 56px Gelica serif weight 700, -1.5px tracking, `{colors.ink}`. Subtitle 20px Articulat CF weight 400, `{colors.ink-muted}`. Green CTA (`{colors.primary}` fill, white text, 8px radius) plus an outline button (white, 1px `{colors.border}`)." - "Card: white, 1px `{colors.border}`, 14px radius, 24px padding. Title 22px Gelica serif weight 600, body 16px Articulat CF `{colors.ink-muted}`." - "Badge: `{colors.primary-soft}` background, `{colors.primary}` text, full pill, 2px 10px padding, 13px Articulat CF weight 500." - "Code block / diff: `{colors.surface-muted}` background, mono 14px, 8px radius, 1px `{colors.border}`." ### Iteration Guide 1. One accent only — green. Everything else is zinc neutral. 2. Serif (Gelica) heads, sans (Articulat CF) body — never mix it up. 3. Borders before shadows; shadows only for hover and overlays. 4. White text on green/dark fills; never small dark text on saturated green. --- ## Attribution Independent design analysis from [Design Swatches](https://designmd.santiagoalonso.com) by [Santiago Alonso](https://santiagoalonso.com). Based on publicly observable interface patterns. Not affiliated with or endorsed by Sparkles. Brand names and trademarks belong to their respective owners.