Functional Minimalist Systems

# Functional Minimalist Systems

## Philosophy

Functional Minimalist Systems is a product design language for interfaces that should feel calm, exact, and immediately usable. It treats reduction as an operational discipline: every visible line, gap, label, and control must clarify what the user can understand or do next. The language favors neutral surfaces, high-contrast text, disciplined grids, restrained typography, and one purposeful accent color so hierarchy comes from spacing and structure rather than decoration.

### Values

- Clarity before personality: the interface should explain itself through alignment, labels, contrast, and predictable component behavior.
- Whitespace as structure: generous empty space separates decisions, groups related content, and creates a quiet rhythm across dense workflows.
- Typographic restraint: two font roles, limited weights, tight tracking, and measured scale changes create hierarchy without visual noise.
- Grid fidelity: content, controls, and data align to an explicit column and spacing system so pages feel engineered rather than arranged by eye.
- Component economy: components are plain, direct, and reusable; ornament is removed unless it improves recognition, state, or accessibility.
- Accessible contrast: minimalism never means low contrast; text, focus states, and status semantics remain legible and perceivable.

### Anti-Values

- Decorative minimalism that removes affordances, hides labels, or makes the product feel precious instead of usable.
- Soft gray-on-gray interfaces where hierarchy depends on subtle contrast that fails accessibility or disappears under glare.
- Arbitrary spacing, floating cards, mixed radii, or decorative dividers that undermine the calm precision of the system.
- Oversized hero typography or trend-driven effects that draw attention away from the user task.

### Visual Character

- Use a strict 12-column grid with 24px gutters on desktop and content rails that snap cards, tables, forms, and navigation to shared vertical edges.
- Apply a restrained neutral palette: off-white page background, white-to-stone surfaces, near-black text, hairline borders, and one high-contrast blue accent for action and focus.
- Create hierarchy primarily through spacing tiers, label case, and font weight changes instead of color fields, shadows, illustrations, or decorative icons.
- Render components with square-to-small 4px corners, one-pixel borders, minimal shadows, visible focus rings, and clear hover states to preserve affordance without ornament.

## Tokens

### Colors

| Name | Value |
|------|-------|
| primary | `#0F172A` |
| secondary | `#475569` |
| accent | `#1D4ED8` |
| background | `#F8FAFC` |
| surface | `#FFFFFF` |
| text | `#0B1120` |
| muted | `#64748B` |
| border | `#CBD5E1` |
| error | `#B91C1C` |
| success | `#047857` |
| warning | `#B45309` |
| info | `#0369A1` |

### Typography

- **Display**: {"font":"IBM Plex Sans","weights":["500","600"],"letter_spacing":"-0.02em","line_height":"1.05"}
- **Body**: {"font":"Source Sans 3","weights":["400","500","600"],"letter_spacing":"-0.02em","line_height":"1.5"}
- **Mono**: {"font":"IBM Plex Mono","weights":["400","500"],"letter_spacing":"-0.02em","line_height":"1.45"}
- **Scale**: {"xs":"0.75rem","sm":"0.875rem","base":"1rem","lg":"1.125rem","xl":"1.5rem","2xl":"2rem","3xl":"2.75rem"}

### Google Fonts Url

https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400;500;600&family=IBM+Plex+Mono:wght@400;500&family=Source+Sans+3:wght@400;500;600&display=swap

### Spacing

- **0**: 0
- **1**: 4px
- **2**: 8px
- **3**: 12px
- **4**: 16px
- **5**: 24px
- **6**: 32px
- **7**: 48px
- **8**: 64px
- **9**: 96px

### Rounded

- **None**: 0
- **Sm**: 4px
- **Md**: 8px
- **Pill**: 9999px

### Shadows

- **None**: none
- **Hairline**: 0 0 0 1px rgba(15,23,42,0.08)
- **Raised**: 0 12px 28px rgba(15,23,42,0.08)

### Surfaces

- **Page**: {colors.background}
- **Panel**: {colors.surface}
- **Subtle**: #F1F5F9
- **Inset**: #E2E8F0

### Borders

- **Default**: 1px solid {colors.border}
- **Strong**: 1px solid #94A3B8
- **Focus**: 2px solid {colors.accent}

### Motion

- **Duration**: 140ms
- **Easing**: cubic-bezier(0.2, 0, 0, 1)
- **Hover Shift**: translateY(-1px)

### Components

- **Button Primary**: background {colors.accent}; color #FFFFFF; radius {rounded.sm}; padding {spacing.3} {spacing.5}; border 1px solid {colors.accent}; font {typography.body};
- **Button Secondary**: background {colors.surface}; color {colors.text}; radius {rounded.sm}; padding {spacing.3} {spacing.5}; border {borders.default};
- **Card**: background {surfaces.panel}; border {borders.default}; radius {rounded.sm}; shadow {shadows.none}; padding {spacing.6};
- **Input**: background {colors.surface}; border {borders.default}; radius {rounded.sm}; padding {spacing.3} {spacing.4}; focus {borders.focus};
- **Table**: monospace numeric cells, 48px rows, hairline dividers, left-aligned labels, right-aligned metrics.

## Rules

### Composition

- Begin every screen with a task-oriented header: one clear title, one sentence of context, and no more than two primary actions.
- Align navigation, cards, table columns, and forms to the same 12-column grid; never center isolated cards unless the workflow is singular.
- Use whitespace blocks of 24px, 48px, and 64px to group information; avoid decorative separators when spacing can express the relationship.
- Prefer flat panels with hairline borders over floating cards; elevation is reserved for transient overlays and active command surfaces.
- Limit accent blue to calls to action, focus rings, selected states, and critical progress indicators so it always means interaction.
- When showing data, pair each metric with a short label and place explanatory text nearby rather than relying on icons or color alone.

### Hierarchy

- Use size changes sparingly: a large page title, medium section headings, and compact labels are enough for most screens.
- Use weight 600 for major headings, weight 500 for labels and controls, and weight 400 for body copy to avoid noisy boldness.
- Use muted text only for secondary explanation; never use muted color for essential instructions, errors, or values.
- Reserve uppercase for short metadata labels and tabs; body text and headings remain sentence case for readability.
- Let alignment and grouping create priority before adding color, icons, badges, or borders.

### Density

Medium-low density with generous whitespace around decision points and tighter rhythm inside tables or form groups. The system should feel calm even when the content is operationally serious.

### Signature Patterns

- A baseline rhythm using 48px section gaps, 24px card padding, and 12px intra-component gaps creates a recognizable measured cadence across screens.
- Minimal status strips combine a 4px left border, plain text labels, and high-contrast semantic color instead of filled alert boxes or icons alone.
- Data rows use monospace numerals, subdued grid lines, and explicit column labels so information feels exact without adding chart decoration.
- Primary action zones sit on the right edge of the grid while explanatory copy occupies the left, reinforcing task flow through position rather than ornament.

## Layout

### Density

Generous but not sparse: large exterior whitespace and compact internal component spacing keep workflows calm while preserving efficiency.

### Grid

- **Desktop**: 12 columns, 72px margins, 24px gutters, 1180px max content width
- **Tablet**: 8 columns, 32px margins, 20px gutters
- **Mobile**: 4 columns, 20px margins, 16px gutters

### Whitespace

Use 64px between major page regions, 48px between sections, 24px within panels, 12px between labels and controls, and 8px for tight metadata relationships.

### Responsive

- **Large**: Side navigation and primary content share the grid; data tables retain columns.
- **Medium**: Navigation collapses into top bar; cards become two-column; tables allow horizontal scroll.
- **Small**: Single-column stack with full-width controls, sticky primary action, and simplified metadata rows.

## Guidance

### Do

- Use whitespace as the first hierarchy tool before adding borders or color.
- Keep component states visible with borders, focus rings, labels, and accessible contrast.
- Use one accent color consistently for selected, focused, and primary actions.
- Write labels directly and place them close to the component they explain.
- Align all major content to the grid, including empty states and form controls.
- Choose simple data displays with clear labels before introducing charts.
- Test contrast for muted text, borders, semantic colors, and focus rings.
- Use sentence-case copy and restrained font weights to keep the interface human.

### Don't

- Do not remove labels in the name of minimalism.
- Do not use pale gray text for important content or disabled-looking active controls.
- Do not mix rounded cards, pill controls, and square tables arbitrarily.
- Do not fill screens with ornamental hero art, gradients, or decorative icons.
- Do not rely on color alone for status, selection, or errors.
- Do not create catalog-style component pages as embodiments; show a real workflow.
- Do not introduce more typefaces or weights to solve hierarchy problems.
- Do not let whitespace become emptiness; every gap should communicate grouping or priority.

### Usage Context

Best for SaaS administration, analytic workbenches, financial operations, internal tools, documentation products, and any interface where trust, speed, and comprehension matter more than brand exuberance.

### Accessibility

Maintain WCAG AA contrast for text and controls, provide 2px visible focus rings, keep labels persistent, pair semantic color with text, preserve 44px touch targets on mobile, and ensure tables have readable headers and keyboard-reachable actions.

---
version: "alpha"
name: "Functional Minimalist Systems"
description: "Agent-curated design language exported from Katagami as DESIGN.md."
colors:
  primary: "#0F172A"
  secondary: "#475569"
  accent: "#1D4ED8"
  background: "#F8FAFC"
  surface: "#FFFFFF"
  text: "#0B1120"
  muted: "#64748B"
  border: "#CBD5E1"
  error: "#B91C1C"
  success: "#047857"
  warning: "#B45309"
  info: "#0369A1"
typography:
  headline-lg:
    fontFamily: "Inter"
    fontSize: "1.953rem"
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: "-0.02em"
  headline-md:
    fontFamily: "Inter"
    fontSize: "1.563rem"
    fontWeight: 600
    lineHeight: 1.15
    letterSpacing: "-0.02em"
  body-md:
    fontFamily: "Inter"
    fontSize: "16px"
    fontWeight: 400
    lineHeight: 1.5
    letterSpacing: "-0.02em"
  label-md:
    fontFamily: "Inter"
    fontSize: "0.75rem"
    fontWeight: 600
    lineHeight: 1
    letterSpacing: "0.08em"
spacing:
  0: "0px"
  1: "4px"
  2: "8px"
  3: "12px"
  4: "16px"
  5: "24px"
  6: "32px"
  7: "48px"
  8: "64px"
  9: "96px"
components:
  color-reference-primary:
    backgroundColor: "{colors.primary}"
  color-reference-secondary:
    backgroundColor: "{colors.secondary}"
  color-reference-accent:
    backgroundColor: "{colors.accent}"
  color-reference-background:
    backgroundColor: "{colors.background}"
  color-reference-surface:
    backgroundColor: "{colors.surface}"
  color-reference-text:
    backgroundColor: "{colors.text}"
  color-reference-muted:
    backgroundColor: "{colors.muted}"
  color-reference-border:
    backgroundColor: "{colors.border}"
  color-reference-error:
    backgroundColor: "{colors.error}"
  color-reference-success:
    backgroundColor: "{colors.success}"
  color-reference-warning:
    backgroundColor: "{colors.warning}"
  color-reference-info:
    backgroundColor: "{colors.info}"
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "#ffffff"
    typography: "{typography.label-md}"
    rounded: "16px"
    padding: "12px"
  card-surface:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.text}"
    rounded: "16px"
    padding: "16px"
  input-default:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.text}"
    rounded: "16px"
    height: "44px"
---

# Functional Minimalist Systems

## Overview

Functional Minimalist Systems is a product design language for interfaces that should feel calm, exact, and immediately usable. It treats reduction as an operational discipline: every visible line, gap, label, and control must clarify what the user can understand or do next. The language favors neutral surfaces, high-contrast text, disciplined grids, restrained typography, and one purposeful accent color so hierarchy comes from spacing and structure rather than decoration.

### Values

- Clarity before personality: the interface should explain itself through alignment, labels, contrast, and predictable component behavior.
- Whitespace as structure: generous empty space separates decisions, groups related content, and creates a quiet rhythm across dense workflows.
- Typographic restraint: two font roles, limited weights, tight tracking, and measured scale changes create hierarchy without visual noise.
- Grid fidelity: content, controls, and data align to an explicit column and spacing system so pages feel engineered rather than arranged by eye.
- Component economy: components are plain, direct, and reusable; ornament is removed unless it improves recognition, state, or accessibility.
- Accessible contrast: minimalism never means low contrast; text, focus states, and status semantics remain legible and perceivable.

### Anti-Values

- Decorative minimalism that removes affordances, hides labels, or makes the product feel precious instead of usable.
- Soft gray-on-gray interfaces where hierarchy depends on subtle contrast that fails accessibility or disappears under glare.
- Arbitrary spacing, floating cards, mixed radii, or decorative dividers that undermine the calm precision of the system.
- Oversized hero typography or trend-driven effects that draw attention away from the user task.

### Visual Character

- Use a strict 12-column grid with 24px gutters on desktop and content rails that snap cards, tables, forms, and navigation to shared vertical edges.
- Apply a restrained neutral palette: off-white page background, white-to-stone surfaces, near-black text, hairline borders, and one high-contrast blue accent for action and focus.
- Create hierarchy primarily through spacing tiers, label case, and font weight changes instead of color fields, shadows, illustrations, or decorative icons.
- Render components with square-to-small 4px corners, one-pixel borders, minimal shadows, visible focus rings, and clear hover states to preserve affordance without ornament.

## Colors

Use the YAML color tokens as the normative palette. The prose below names the roles agents should preserve when generating UI.

| Token | Value |
|-------|-------|
| primary | `#0F172A` |
| secondary | `#475569` |
| accent | `#1D4ED8` |
| background | `#F8FAFC` |
| surface | `#FFFFFF` |
| text | `#0B1120` |
| muted | `#64748B` |
| border | `#CBD5E1` |
| error | `#B91C1C` |
| success | `#047857` |
| warning | `#B45309` |
| info | `#0369A1` |

## Typography

- **Headline-Lg**: Inter, 1.953rem, weight 700, line-height 1.1.
- **Headline-Md**: Inter, 1.563rem, weight 600, line-height 1.15.
- **Body-Md**: Inter, 16px, weight 400, line-height 1.5.
- **Label-Md**: Inter, 0.75rem, weight 600, line-height 1.

## Layout

### Spacing Tokens

- **0**: `0px`
- **1**: `4px`
- **2**: `8px`
- **3**: `12px`
- **4**: `16px`
- **5**: `24px`
- **6**: `32px`
- **7**: `48px`
- **8**: `64px`
- **9**: `96px`

### Density

Generous but not sparse: large exterior whitespace and compact internal component spacing keep workflows calm while preserving efficiency.

### Grid

- **Desktop**: 12 columns, 72px margins, 24px gutters, 1180px max content width
- **Tablet**: 8 columns, 32px margins, 20px gutters
- **Mobile**: 4 columns, 20px margins, 16px gutters

### Whitespace

Use 64px between major page regions, 48px between sections, 24px within panels, 12px between labels and controls, and 8px for tight metadata relationships.

### Responsive

- **Large**: Side navigation and primary content share the grid; data tables retain columns.
- **Medium**: Navigation collapses into top bar; cards become two-column; tables allow horizontal scroll.
- **Small**: Single-column stack with full-width controls, sticky primary action, and simplified metadata rows.

## Elevation & Depth

### Shadows

- **None**: none
- **Hairline**: 0 0 0 1px rgba(15,23,42,0.08)
- **Raised**: 0 12px 28px rgba(15,23,42,0.08)

## Shapes

### Surfaces

- **Page**: {colors.background}
- **Panel**: {colors.surface}
- **Subtle**: #F1F5F9
- **Inset**: #E2E8F0

### Borders

- **Default**: 1px solid {colors.border}
- **Strong**: 1px solid #94A3B8
- **Focus**: 2px solid {colors.accent}

## Components

### Composition

- Begin every screen with a task-oriented header: one clear title, one sentence of context, and no more than two primary actions.
- Align navigation, cards, table columns, and forms to the same 12-column grid; never center isolated cards unless the workflow is singular.
- Use whitespace blocks of 24px, 48px, and 64px to group information; avoid decorative separators when spacing can express the relationship.
- Prefer flat panels with hairline borders over floating cards; elevation is reserved for transient overlays and active command surfaces.
- Limit accent blue to calls to action, focus rings, selected states, and critical progress indicators so it always means interaction.
- When showing data, pair each metric with a short label and place explanatory text nearby rather than relying on icons or color alone.

### Hierarchy

- Use size changes sparingly: a large page title, medium section headings, and compact labels are enough for most screens.
- Use weight 600 for major headings, weight 500 for labels and controls, and weight 400 for body copy to avoid noisy boldness.
- Use muted text only for secondary explanation; never use muted color for essential instructions, errors, or values.
- Reserve uppercase for short metadata labels and tabs; body text and headings remain sentence case for readability.
- Let alignment and grouping create priority before adding color, icons, badges, or borders.

### Density

Medium-low density with generous whitespace around decision points and tighter rhythm inside tables or form groups. The system should feel calm even when the content is operationally serious.

### Signature Patterns

- A baseline rhythm using 48px section gaps, 24px card padding, and 12px intra-component gaps creates a recognizable measured cadence across screens.
- Minimal status strips combine a 4px left border, plain text labels, and high-contrast semantic color instead of filled alert boxes or icons alone.
- Data rows use monospace numerals, subdued grid lines, and explicit column labels so information feels exact without adding chart decoration.
- Primary action zones sit on the right edge of the grid while explanatory copy occupies the left, reinforcing task flow through position rather than ornament.

## shadcn/ui Usage

When the target app uses shadcn/ui, copy DESIGN.md with shadcn instead of the plain DESIGN.md. It contains the same Katagami design-language source plus the shadcn/ui primitives, imports, theme variables, component recipes, and preview-shot guidance.

DESIGN.md with shadcn: `/language/en-019dde35-8f7c-7bd1-ae2e-f65ba4bb1dd1/DESIGN.with-shadcn.md`.

The shadcn page also exposes optional machine-readable files for automation, but the human-facing handoff is DESIGN.md with shadcn.

Install recommended primitives with `npx shadcn@latest add button card input textarea select dialog sheet tabs badge separator checkbox switch slider tooltip dropdown-menu table`.

Use these primitives in shadcn apps:
- button
- card
- input
- textarea
- select
- dialog
- sheet
- tabs
- badge
- separator
- checkbox
- switch
- slider
- tooltip
- dropdown-menu
- table

Implementation rule for agents: import shadcn primitives from `@/components/ui/*`, apply the generated CSS variables first, then compose the language-specific recipes from the companion MD. Katagami remains the source of truth; shadcn names are the implementation surface.

## Do's and Don'ts

- Do Use whitespace as the first hierarchy tool before adding borders or color.
- Do Keep component states visible with borders, focus rings, labels, and accessible contrast.
- Do Use one accent color consistently for selected, focused, and primary actions.
- Do Write labels directly and place them close to the component they explain.
- Do Align all major content to the grid, including empty states and form controls.
- Do Choose simple data displays with clear labels before introducing charts.
- Do Test contrast for muted text, borders, semantic colors, and focus rings.
- Do Use sentence-case copy and restrained font weights to keep the interface human.
- Don't Do not remove labels in the name of minimalism.
- Don't Do not use pale gray text for important content or disabled-looking active controls.
- Don't Do not mix rounded cards, pill controls, and square tables arbitrarily.
- Don't Do not fill screens with ornamental hero art, gradients, or decorative icons.
- Don't Do not rely on color alone for status, selection, or errors.
- Don't Do not create catalog-style component pages as embodiments; show a real workflow.
- Don't Do not introduce more typefaces or weights to solve hierarchy problems.
- Don't Do not let whitespace become emptiness; every gap should communicate grouping or priority.

### Usage Context

Best for SaaS administration, analytic workbenches, financial operations, internal tools, documentation products, and any interface where trust, speed, and comprehension matter more than brand exuberance.

### Accessibility

Maintain WCAG AA contrast for text and controls, provide 2px visible focus rings, keep labels persistent, pair semantic color with text, preserve 44px touch targets on mobile, and ensure tables have readable headers and keyboard-reachable actions.

```json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "functional-minimalist-systems",
  "type": "registry:theme",
  "title": "Functional Minimalist Systems shadcn Theme",
  "cssVars": {
    "theme": {},
    "light": {
      "background": "#F8FAFC",
      "foreground": "#0B1120",
      "card": "#FFFFFF",
      "card-foreground": "#0B1120",
      "popover": "#FFFFFF",
      "popover-foreground": "#0B1120",
      "primary": "#0F172A",
      "primary-foreground": "#ffffff",
      "secondary": "#475569",
      "secondary-foreground": "#ffffff",
      "muted": "#64748B",
      "muted-foreground": "#0B1120",
      "accent": "#1D4ED8",
      "accent-foreground": "#ffffff",
      "destructive": "#B91C1C",
      "border": "#CBD5E1",
      "input": "#CBD5E1",
      "ring": "#1D4ED8",
      "chart-1": "#0F172A",
      "chart-2": "#475569",
      "chart-3": "#1D4ED8",
      "chart-4": "#047857",
      "chart-5": "#B45309",
      "sidebar": "#FFFFFF",
      "sidebar-foreground": "#0B1120",
      "sidebar-primary": "#0F172A",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#0369A1",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#CBD5E1",
      "sidebar-ring": "#1D4ED8",
      "radius": "0.625rem"
    },
    "dark": {
      "background": "#0f1115",
      "foreground": "#f8fafc",
      "card": "#181b22",
      "card-foreground": "#f8fafc",
      "popover": "#181b22",
      "popover-foreground": "#f8fafc",
      "primary": "#0F172A",
      "primary-foreground": "#ffffff",
      "secondary": "#252a33",
      "secondary-foreground": "#f8fafc",
      "muted": "#252a33",
      "muted-foreground": "#a1a1aa",
      "accent": "#1D4ED8",
      "accent-foreground": "#ffffff",
      "destructive": "#B91C1C",
      "border": "#303642",
      "input": "#303642",
      "ring": "#1D4ED8",
      "chart-1": "#0F172A",
      "chart-2": "#475569",
      "chart-3": "#1D4ED8",
      "chart-4": "#047857",
      "chart-5": "#B45309",
      "sidebar": "#181b22",
      "sidebar-foreground": "#f8fafc",
      "sidebar-primary": "#0F172A",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#1D4ED8",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#303642",
      "sidebar-ring": "#1D4ED8",
      "radius": "0.625rem"
    }
  },
  "meta": {
    "source": "katagami",
    "languageId": "en-019dde35-8f7c-7bd1-ae2e-f65ba4bb1dd1",
    "slug": "functional-minimalist-systems",
    "componentManifest": [
      "button",
      "card",
      "input",
      "textarea",
      "select",
      "dialog",
      "sheet",
      "tabs",
      "badge",
      "separator",
      "checkbox",
      "switch",
      "slider",
      "tooltip",
      "dropdown-menu",
      "table"
    ],
    "installCommand": "npx shadcn@latest add button card input textarea select dialog sheet tabs badge separator checkbox switch slider tooltip dropdown-menu table",
    "nativeTokenNames": {
      "colors": [
        "accent",
        "background",
        "border",
        "error",
        "info",
        "muted",
        "primary",
        "secondary",
        "success",
        "surface",
        "text",
        "warning"
      ],
      "typography": [
        "body",
        "display",
        "mono",
        "scale"
      ],
      "spacing": [
        "0",
        "1",
        "2",
        "3",
        "4",
        "5",
        "6",
        "7",
        "8",
        "9"
      ],
      "rounded": [
        "md",
        "none",
        "pill",
        "sm"
      ],
      "shadows": [
        "hairline",
        "none",
        "raised"
      ],
      "surfaces": [
        "inset",
        "page",
        "panel",
        "subtle"
      ],
      "borders": [
        "default",
        "focus",
        "strong"
      ],
      "motion": [
        "duration",
        "easing",
        "hover_shift"
      ],
      "components": [
        "button_primary",
        "button_secondary",
        "card",
        "input",
        "table"
      ]
    }
  }
}
```