Skip to content

Instantly share code, notes, and snippets.

@MisreadableMind

MisreadableMind/style-guide.md

Created February 23, 2026 20:14
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save MisreadableMind/57e8fdb8fdeaaa5456999b5e8110df7b to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save MisreadableMind/57e8fdb8fdeaaa5456999b5e8110df7b to your computer and use it in GitHub Desktop.
Download ZIP
Style Guide Command for Claude Code, just place it under .claude/commands and run like/style-guide "additional hints/instructions"
Raw
style-guide.md
description allowed-tools argument-hint
Analyze the project's existing styles and generate a comprehensive style guide
Read, Write, Edit, Glob, Grep, Bash
<output-file-path (e.g. style-guide.html)>

Analyze the current project's codebase to extract its design system, then generate a standalone style guide HTML page documenting it. Write the output to: $ARGUMENTS (default to style-guide.html in the current working directory if no argument given).

Phase 1: Discovery

Thoroughly scan the project to extract the existing design language. Search for ALL of the following:

1.1 Color Tokens

  • Search CSS/SCSS/LESS/Tailwind config for color variables (--color-*, $color-*, theme colors)
  • Search for raw hex values, rgb/rgba/hsl values used repeatedly
  • Identify: primary, secondary, accent, background, surface, text, border, error, warning, success, info colors
  • Check for dark/light theme definitions
  • Look in: :root, theme(), tailwind.config.*, **/variables.*, **/tokens.*, **/theme.*, **/colors.*

1.2 Typography

  • Find font-family declarations, Google Fonts imports, @font-face rules
  • Extract the type scale: all font-size values and where they're used
  • Map font weights, line-heights, letter-spacing values
  • Identify heading hierarchy (h1-h6 styles)
  • Look in: global styles, typography files, tailwind config, design token files

1.3 Spacing

  • Extract spacing scale (padding/margin values, gap values)
  • Find container max-widths, section padding patterns
  • Look for spacing tokens/variables

1.4 Layout & Grid

  • Identify grid systems in use (CSS Grid, Flexbox patterns, grid frameworks)
  • Find common column layouts, breakpoints
  • Extract container patterns

1.5 Components

  • Identify reusable UI components: buttons, cards, inputs, badges/tags, navigation, modals, alerts, etc.
  • Extract their styles: backgrounds, borders, border-radius, shadows, padding
  • Note hover/focus/active states

1.6 Motion & Interaction

  • Find transition/animation definitions
  • Extract easing curves, durations
  • Identify hover patterns, focus styles

1.7 Icons

  • Check for icon systems (SVG sprites, icon fonts, icon libraries)
  • Note icon sizing conventions

1.8 Responsive Breakpoints

  • Extract all media query breakpoints
  • Note mobile-first vs desktop-first approach

1.9 Project Identity

  • Find the project name from package.json, README, or HTML titles
  • Look for logos or brand assets

Phase 2: Generate Style Guide

Create a single self-contained HTML file with these sections:

Required Sections

  1. Header/Navigation -- Project name, "Style Guide" label, light/dark theme toggle
  2. Colors -- Every discovered color as a swatch with name, value, and usage note. Group by role (backgrounds, text, accents, borders, states).
  3. Typography -- Live-rendered examples of every text style found (headings h1-h6, body, small, labels, etc.) showing font family, weight, size, line-height, letter-spacing.
  4. Spacing -- Visual representation of the spacing scale (show boxes at each size).
  5. Layout -- Document container widths, grid patterns, column layouts with live examples.
  6. Components -- Live interactive previews of every UI component found (buttons in all variants, cards, inputs, badges, nav, alerts, etc.). Show default + hover + active + disabled states where applicable.
  7. Motion -- Document transitions, easing curves, animation durations. Show interactive hover demos.
  8. Icons -- Show all icon styles/sizes found.
  9. Responsive -- List all breakpoints and what changes at each.

Style Guide Page Itself

The style guide page should:

  • Use the project's OWN discovered design tokens for styling (so it feels native to the project)
  • Support a light/dark toggle using data-theme attribute on <html>, persisted via localStorage
  • Component previews render on a neutral background that shows them accurately
  • Include smooth scroll navigation
  • Use IntersectionObserver for scroll-based reveal animations
  • Be fully responsive

Technical Requirements

  • Single HTML file -- all CSS inline in <style>, all JS inline in <script>
  • No external dependencies except Google Fonts if the project uses them
  • No build tools, no frameworks
  • CSS organized with comment section headers
  • Self-contained: drop the file anywhere and it works

Phase 3: Write & Confirm

  1. Write the complete HTML file to the specified output path.
  2. Report a summary of what was discovered and documented:
    • Number of colors found
    • Font families found
    • Number of components documented
    • Breakpoints found
    • Any notable patterns or conventions detected

Fallback: Minimal Clean Design System

If the project has NO existing styles (no CSS files, no design tokens, no UI framework), use this complete fallback design system. It is a clean, minimalist, light-first aesthetic.

Fallback Color Tokens

:root {
    /* Backgrounds */
    --color-bg:            #ffffff;
    --color-bg-alt:        #f8f9fa;
    --color-bg-subtle:     #f1f3f5;
    --color-surface:       #ffffff;
    --color-surface-hover: #f8f9fa;

    /* Text */
    --color-text:          #1a1a2e;
    --color-text-2:        #4a4a68;
    --color-text-3:        #8b8ba3;
    --color-text-muted:    #adb5bd;

    /* Borders & Dividers */
    --color-border:        #e9ecef;
    --color-border-strong: #dee2e6;
    --color-divider:       #f1f3f5;

    /* Primary Accent */
    --color-primary:       #2563eb;
    --color-primary-hover: #1d4ed8;
    --color-primary-light: #eff6ff;
    --color-primary-text:  #ffffff;

    /* States */
    --color-success:       #16a34a;
    --color-success-light: #f0fdf4;
    --color-warning:       #d97706;
    --color-warning-light: #fffbeb;
    --color-error:         #dc2626;
    --color-error-light:   #fef2f2;
    --color-info:          #2563eb;
    --color-info-light:    #eff6ff;

    /* Shadows */
    --shadow-sm:    0 1px 2px rgba(0,0,0,0.04);
    --shadow-md:    0 2px 8px rgba(0,0,0,0.06);
    --shadow-lg:    0 4px 16px rgba(0,0,0,0.08);
    --shadow-focus: 0 0 0 3px rgba(37,99,235,0.15);
}

Dark mode override:

[data-theme="dark"] {
    --color-bg:            #0f0f13;
    --color-bg-alt:        #16161d;
    --color-bg-subtle:     #1c1c26;
    --color-surface:       #1c1c26;
    --color-surface-hover: #242430;
    --color-text:          #e8e8ed;
    --color-text-2:        #a0a0b8;
    --color-text-3:        #6b6b80;
    --color-text-muted:    #4a4a5c;
    --color-border:        #2a2a38;
    --color-border-strong: #3a3a4a;
    --color-divider:       #1c1c26;
    --color-primary:       #3b82f6;
    --color-primary-hover: #60a5fa;
    --color-primary-light: rgba(59,130,246,0.1);
    --color-success-light: rgba(22,163,74,0.1);
    --color-warning-light: rgba(217,119,6,0.1);
    --color-error-light:   rgba(220,38,38,0.1);
    --color-info-light:    rgba(37,99,235,0.1);
    --shadow-sm:    0 1px 2px rgba(0,0,0,0.2);
    --shadow-md:    0 2px 8px rgba(0,0,0,0.3);
    --shadow-lg:    0 4px 16px rgba(0,0,0,0.4);
    --shadow-focus: 0 0 0 3px rgba(59,130,246,0.25);
}

Fallback Typography

Font: Inter (via Google Fonts). Single family, clean and neutral.

<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
:root {
    --font-sans: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
    --font-mono: 'SF Mono', 'Fira Code', 'Fira Mono', 'Roboto Mono', monospace;
}

Type scale:

Role Size Weight Line-height Letter-spacing Color
Display / Hero clamp(36px, 5vw, 56px) 700 1.1 -0.025em --color-text
H1 32px 700 1.2 -0.02em --color-text
H2 24px 600 1.3 -0.015em --color-text
H3 20px 600 1.4 -0.01em --color-text
H4 16px 600 1.4 0 --color-text
Body 15px 400 1.65 0 --color-text-2
Body small 13px 400 1.55 0 --color-text-3
Label 12px 500 1.2 0.03em --color-text-3
Caption / Meta 11px 500 1.2 0.04em --color-text-muted
Code 13px (mono) 400 1.5 0 --color-text

Rules:

  • Inter handles everything: headings, body, labels. Hierarchy via weight and size only.
  • Headings use -0.02em to -0.01em negative letter-spacing for tighter display.
  • Labels and captions use slight positive letter-spacing (uppercase optional).
  • Body text uses --color-text-2, not pure --color-text, for comfortable reading.
  • Enable -webkit-font-smoothing: antialiased.

Fallback Spacing Scale

:root {
    --space-1:  4px;
    --space-2:  8px;
    --space-3:  12px;
    --space-4:  16px;
    --space-5:  24px;
    --space-6:  32px;
    --space-7:  48px;
    --space-8:  64px;
    --space-9:  96px;
    --space-10: 128px;
}
  • Container: max-width 960px, margin 0 auto, padding 0 24px.
  • Section padding: 80px 0 (64px on mobile).
  • Card padding: 24px.

Fallback Border Radius

:root {
    --radius-sm:   4px;
    --radius-md:   8px;
    --radius-lg:   12px;
    --radius-full: 9999px;
}
  • Buttons: --radius-md
  • Cards: --radius-lg
  • Inputs: --radius-md
  • Badges/Tags: --radius-full
  • Avatars: --radius-full

Fallback Components

Button (Primary):

  • Background: --color-primary. Color: --color-primary-text.
  • Padding: 10px 20px. Font: 14px, weight 500.
  • Border-radius: --radius-md. Border: none.
  • Hover: --color-primary-hover. Transition: 0.15s ease.
  • Focus: --shadow-focus outline.
  • Disabled: opacity 0.5, cursor not-allowed.

Button (Secondary):

  • Background: transparent. Color: --color-text-2.
  • Border: 1px solid --color-border-strong.
  • Hover: background --color-bg-alt, border-color --color-text-3.

Button (Ghost):

  • Background: transparent. Color: --color-text-2. Border: none.
  • Hover: background --color-bg-alt.

Card:

  • Background: --color-surface. Border: 1px solid --color-border.
  • Border-radius: --radius-lg. Padding: 24px.
  • Shadow: --shadow-sm. Hover: --shadow-md, border-color --color-border-strong.

Input:

  • Background: --color-bg. Border: 1px solid --color-border-strong.
  • Border-radius: --radius-md. Padding: 10px 14px. Font: 15px.
  • Focus: border-color --color-primary, --shadow-focus.
  • Placeholder: --color-text-muted.

Badge / Tag:

  • Padding: 3px 10px. Font: 11px, weight 500.
  • Border-radius: --radius-full. Background: --color-bg-subtle.
  • Color: --color-text-3.
  • Colored variants: use --color-*-light as bg with matching text color.

Alert / Notice:

  • Padding: 14px 18px. Border-radius: --radius-md.
  • Border-left: 3px solid (accent color).
  • Background: corresponding --color-*-light. Font: 14px.

Divider:

  • Height: 1px. Background: --color-divider.
  • Full width or with horizontal margin.

Navigation:

  • Height: 56px. Background: --color-bg with backdrop-filter: blur(12px).
  • Position: sticky top 0. Border-bottom: 1px solid --color-border.
  • Brand: 16px weight 700. Links: 14px weight 500, --color-text-3 -> --color-text on hover.

Fallback Motion

:root {
    --ease: cubic-bezier(0.25, 0.1, 0.25, 1);
    --duration-fast:   0.15s;
    --duration-normal: 0.25s;
    --duration-slow:   0.4s;
}
  • Buttons, links, borders: --duration-fast
  • Cards, complex hovers: --duration-normal
  • Scroll reveals, overlays: --duration-slow
  • Scroll reveal: translateY(20px), opacity 0 -> 1. IntersectionObserver threshold 0.1.
  • No bouncy or elastic easing. Smooth and subtle only.

Fallback Responsive Breakpoints

Name Width Notes
sm 640px Stack columns, smaller padding
md 768px 2-column layouts
lg 1024px Full layout

Mobile-first approach: base styles are mobile, layer up with min-width queries.

Fallback Design Principles

  1. White space is the primary design element. Generous padding, breathing room.
  2. Hierarchy through weight and size, not color. Headings are bolder and larger, not flashier.
  3. One accent color (blue) for interactive elements. Everything else is grayscale.
  4. Subtle borders and shadows for depth. Never heavy or distracting.
  5. Rounded but not bubbly. 8-12px radius, not 24px. Clean, not cute.
  6. Dark mode is a true inversion, not an afterthought. Same hierarchy and spacing, just flipped.

Rules

  • Only document what ACTUALLY EXISTS in the project. Do not invent or assume styles.
  • If the project has no styles or very few styles: use the Fallback Minimal Clean Design System defined above as the complete baseline. Generate the style guide using the fallback tokens, components, and conventions. Note in the guide that this is a suggested starter design system.
  • If the project uses a framework (Tailwind, Bootstrap, MUI, etc.), document the project's customizations on top of that framework, not the framework defaults.
  • Every component preview must be a real, interactive rendered example -- not a description or screenshot.
  • Use code snippets alongside previews so developers can copy the markup/CSS.
  • Group related items logically. Use clear section labels.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment