Skip to content

Basinfy/Basinfy-SaaS-Studio / .agents/skills/saas-design-tokens

saas-design-tokens

Unverified

Author semantic UI design tokens, color scales, typography, and component primitives.

Running this workflow on this client

Run commands from the project root (use Git Bash on Windows if bash points to an unavailable WSL distro). Shared studio files live in .claude/; follow .agents/PORTABLE-RUNTIME.md and .claude/docs/config-resolution.md for client tools, delegation, and approval rules.

Run bash .claude/hooks/yaml-helper.sh resolve_config --keys locale,review_mode,automation,workflow,docs.density and use its output below.

Resolved above — use as-is; --review overrides review_mode. No block → defaults in .claude/docs/config-resolution.md.

Design Tokens & Semantic UI Spec

Locale & User Profile: Match locale (pt-BR → natural Brazilian Portuguese questions/options, overriding English examples; en → English) and user_profile (founder → plain business language with (Recomendado) first, zero tech jargon; developer → technical). Keep code/tests in English.

The Design Tokens & Semantic UI Spec establishes the foundational design language, semantic color system, typography scale, spacing tokens, and component styling for the entire SaaS application. It gates all UI and frontend asset development.


Phase 0: Parse Arguments and Context Check

Every AskUserQuestion call follows .claude/docs/automation-modes.md (collaborative asks always · guided major-only · autonomous logs and proceeds; automation_always_ask categories always prompt).

docs.density: controls per-section depth:

  • terse (minimal rigor) = bulleted tokens and values with concise rationale
  • balanced (standard rigor) = token tables with component usage guidance
  • thorough (high rigor) = full visual rationale, accessibility contrast calculations, and CSS code blocks

workflow:

  • full — all 8 design token sections required.
  • standard — sections 1–4 required; sections 5–8 as appropriate for the scope.
  • minimal — core tokens (colors, typography, spacing).

Context Check: Read design/prd/product-concept.md or design/product-brief.md. Use design/product-concept.md as a legacy fallback. If none exists, prompt:

"No product concept found. Run /saas-brainstorm first to establish product pillars and target audience."


Phase 1: Framing

Identify the product's primary design direction:

  1. Target Audience & Market: B2B enterprise, developer tool, consumer SaaS, fintech, or creator economy.
  2. Visual Archetype:
    • Technical / Utilitarian: Monospace accents, high-contrast borders, dense grids (e.g. Linear, Vercel, Supabase).
    • Minimalist / Swiss: Strong typography, generous white space, restrained palette (e.g. Notion, iA Writer).
    • Enterprise / Polished: Accessible neutrals, prominent brand accent, structured tables (e.g. Stripe, Salesforce).
    • Friendly / Modern: Soft curves, vibrant accents, micro-illustrations (e.g. Loom, Slack, Mailchimp).

[!TIP] Anti-Slop Foundations (/saas-frontend-taste): Leverage curated, production-tested palettes (.claude/skills/saas-frontend-taste/library/palettes.json) and typography pairings (library/type.json) calibrated for SaaS archetypes (Linear, Stripe, Vercel, x.ai).

Phase 2: Core Token Foundation (Sections 1–4)

Section 1: Design Philosophy & Personality

Define 3-4 visual design principles (e.g., "Clarity over Decoration", "Speed in Every Interaction", "Calm and Focused Workspaces").

Section 2: Semantic Color System

Define hex, HSL, or OKLCH values for:

  1. Primitives: Neutral scale (50 to 950), Brand primary scale (50 to 950).
  2. Semantic Tokens (Light & Dark themes):
    • background and foreground
    • card, card-foreground
    • popover, popover-foreground
    • primary, primary-foreground
    • secondary, secondary-foreground
    • muted, muted-foreground
    • accent, accent-foreground
    • destructive, destructive-foreground
    • border, input, ring
    • status: Success (green), Warning (amber), Error (red), Info (blue).
  3. Contrast Validation: Verify all text on background pairings satisfy WCAG 2.2 AA (minimum 4.5:1 for normal text, 3:1 for large text).

Section 3: Typography System

Define font stacks and scales:

  1. Font Families:
    • Sans: Primary UI font (e.g. Inter, Geist, Plus Jakarta Sans, system-ui).
    • Mono: Code and numeric tables (e.g. Geist Mono, JetBrains Mono).
  2. Type Scale:
    • xs: 12px / 16px line-height
    • sm: 14px / 20px line-height (standard body)
    • base: 16px / 24px line-height (lead body)
    • lg: 18px / 28px line-height
    • xl: 20px / 28px line-height (H4)
    • 2xl: 24px / 32px line-height (H3)
    • 3xl: 30px / 36px line-height (H2)
    • 4xl: 36px / 40px line-height (H1)
  3. Font Weights: Regular (400), Medium (500), Semibold (600), Bold (700).

Section 4: Spacing, Grid & Elevation

  1. Spacing Scale: 4px base (4, 8, 12, 16, 24, 32, 48, 64px).
  2. Radius Tokens: radius-sm (4px), radius-md (8px), radius-lg (12px), radius-xl (16px), radius-full (9999px).
  3. Elevation & Shadows: shadow-xs, shadow-sm, shadow-md, shadow-lg, shadow-modal.
  4. Z-Index Scale: Base (0), Dropdown (50), Sticky (100), Modal Backdrop (200), Modal (201), Toast (300).

Phase 3: Component Systems & Standards (Sections 5–8)

Section 5: Component Styling & Variants

Specify visual standards for core UI building blocks:

  • Buttons: Primary (solid brand), Secondary (outline), Ghost, Destructive, Link. All states: default, hover, active, focus-visible, disabled, loading (with spinner).
  • Inputs & Forms: Focus rings, error borders, floating labels, helper text styling.
  • Badges & Tags: Status pills (Success, Warning, Info, Neutral) with consistent padding and typography.
  • Cards & Containers: Surface colors, border contrast, subtle hover lifts.

Section 6: Iconography & Visual Assets

  1. Icon Set: Selected library (e.g. Lucide React, Heroicons, Radix Icons).
  2. Stroke Width & Sizes: 16px (inline/small), 20px (standard UI), 24px (features/large).
  3. Empty State & Marketing Visuals: Style guide for empty state illustrations, avatars, and hero graphics.

Section 7: Navigation & App Shell Tokens

  1. Sidebar Tokens: Background, active route highlight, collapsed icon rail width (64px), expanded width (240px).
  2. Topbar Tokens: Height (56px/64px), border color, backdrop blur (backdrop-blur-md).
  3. Command Palette (Cmd+K): Modal overlay blur, search item highlight token, shortcut badge styling.

Section 8: Web Asset Standards & Export Formats

  1. File Format Rules:
    • Vector icons & logos: SVG (optimized with SVGO, remove hardcoded dimensions/fills).
    • Product screenshots & graphics: WebP / AVIF (fallback PNG).
    • Fonts: WOFF2 with font-display: swap.
  2. File Size Budgets:
    • SVGs: < 30KB
    • Product images / banners: < 200KB
    • Total initial CSS bundle: < 50KB gzipped
  3. Code Export:
    • Generate Tailwind config tokens (tailwind.config.ts) or CSS variables (globals.css).

Phase 4: Save & Export

Write the completed specification to design/tokens/design-tokens.md (and generate src/styles/tokens.css or Tailwind theme values if source directory exists).


Phase 5: Design System Director Sign-Off

Execute review check with design-system-director agent:

  1. Are all color pairings accessible (WCAG 2.2 AA compliant)?
  2. Is the type scale cohesive with appropriate line heights?
  3. Are light and dark theme tokens fully balanced?

Output Verdict:

  • APPROVED: Design tokens complete and approved for UI production.
  • NEEDS REVISION: List exact token discrepancies to resolve.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall