> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kombai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> A Design System captures a project's full visual identity — palette, typography, spacing, elevation, and more — so Kombai can generate and code designs that are consistent with it.

export const PaletteIcon = props => {
  return <div style={{
    display: "inline",
    justifyContent: "center",
    alignItems: "center"
  }}>
      <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true" style={{
    display: "inline"
  }} {...props}>
        <path d="M12 22a1 1 0 0 1 0-20 10 9 0 0 1 10 9 5 5 0 0 1-5 5h-2.25a1.75 1.75 0 0 0-1.4 2.8l.3.4a1.75 1.75 0 0 1-1.4 2.8z"></path>
        <circle cx="13.5" cy="6.5" r=".5" fill="currentColor"></circle>
        <circle cx="17.5" cy="10.5" r=".5" fill="currentColor"></circle>
        <circle cx="6.5" cy="12.5" r=".5" fill="currentColor"></circle>
        <circle cx="8.5" cy="7.5" r=".5" fill="currentColor"></circle>
      </svg>
    </div>;
};

A Design System is a structured, file-based spec of a product's visual language. Instead of managing separate color palettes, type scales, and freeform style notes, a Design System brings every layer of a visual identity together, from brand colors and typography down to spacing, elevation, grids, and usage guidelines, in a single artifact that Kombai can read, edit, and apply consistently across your designs and code.

Kombai can generate a Design System from an existing codebase, a Figma file, a `Design.md` file, a design on your Canvas, or a live website. Every Design System is stored as a `.ds` file in your user-wide Kombai library at `~/.kombai/design-systems/`, so it is available across all your projects. A `.ds` file placed anywhere inside a project is also discovered automatically. A `.ds` file is Markdown with a YAML front-matter block — the front matter holds the structured tokens, and the Markdown body holds the prose guidance.

## Design System structure

A Design System has two layers: a YAML **front matter** block holding the structured tokens, and a Markdown **body** holding prose guidance organized into sections.

The front matter holds the hard data: the color palette and its semantic roles (e.g. `background.canvas`, `text.primary`, `border.focus`), gradients, font families and text styles, spacing, radius, shadows and elevation levels, border widths and styles, opacity levels, motion durations and easings, breakpoints, component specs, asset patterns, icon glyphs, and motion patterns.

The body is organized into the following sections. Click each to see what it covers.

<AccordionGroup>
  <Accordion title="Instructions">
    How to apply the system when building UI — which token to reach for, usage and scarcity constraints, and the system's voice.
  </Accordion>

  <Accordion title="Brand & Accent">
    Usage of each brand and accent color in the palette.
  </Accordion>

  <Accordion title="Surface">
    Usage of each surface and background color across pages, cards, and containers.
  </Accordion>

  <Accordion title="Text">
    Usage of each text color — headings, body copy, secondary text, and links.
  </Accordion>

  <Accordion title="Status & Semantic">
    Usage of status, overlay, and semantic colors (success, warning, error, info) for badges, links, and highlights.
  </Accordion>

  <Accordion title="Fonts">
    Font families and what each carries, type principles, and recommended substitutes.
  </Accordion>

  <Accordion title="Layout">
    Max content width, grid columns, gutters, and whitespace philosophy.
  </Accordion>

  <Accordion title="Responsiveness">
    Per-component collapsing rules across breakpoints — nav, hero, grids, footer, and touch targets.
  </Accordion>

  <Accordion title="Shape & Geometry">
    Radius-scale usage plus photography and illustration geometry.
  </Accordion>

  <Accordion title="Assets">
    The imagery and media narrative, including generation prompts for reusable assets.
  </Accordion>

  <Accordion title="Iconography">
    Icon style and usage narrative; the icon glyphs themselves live in the front matter.
  </Accordion>

  <Accordion title="Components">
    A one-line usage note per component covered by the Design System.
  </Accordion>

  <Accordion title="Animation & Motion">
    The motion narrative — signature transitions and any JS-, video-, or canvas-driven motion that can't be expressed as CSS tokens.
  </Accordion>

  <Accordion title="Do">
    Recommended practices for applying the Design System.
  </Accordion>

  <Accordion title="Don't">
    Anti-patterns to avoid, e.g. color pairings or spacing rules that break the system.
  </Accordion>

  <Accordion title="Signature">
    Distinctive, system-specific details: signature components, brand gradients, color-block patterns, and decorative depth.
  </Accordion>

  <Accordion title="Notes">
    Catch-all for actionable caveats, known gaps, and edge cases that don't fit another section.
  </Accordion>
</AccordionGroup>

## Design System Gallery

The Design System Gallery is where you browse, create, and manage Design Systems. It has two tabs:

* **Public design systems:** A curated library of Design Systems extracted from popular, real-world products (e.g. Discord, Stripe, Nike). Use the category filters at the top (for example **AI & LLM**, **Fintech**, or **Ecommerce**) to narrow down the list, or use **My design systems** to build your own.
* **My design systems:** All the Design Systems you've created or imported into your workspace. Each row shows the Design System's name, its color palette, its typography, and when it was last modified.

## View a Design System

Click on a Design System card or row to open its detail page. The detail page shows:

* The Design System's **name**, **slug**, and an AI-generated description summarizing its overall visual identity.
* The sections listed in [Design System structure](#design-system-structure), with the individual tokens shown as cards, each with a swatch or value, its token name, and its raw value (e.g. a hex code). Click the copy icon on any card to copy its value. Click **Edit** to edit the raw Markdown source of the `.ds` file directly.

See [Create a Design System](./create) for the different ways to generate one, and [Manage a Design System](./manage) for how to edit, apply, attach, and delete one.