# 8StarLabs Design System

> 8StarLabs develops carefully curated software products, shaped through thoughtful design and reliable engineering.

This document describes the 8StarLabs design language: brand, color, typography,
spacing, and component conventions. It is published at https://www.8starlabs.com/design.md
as a stable, machine-readable reference for designers, engineers, and AI agents.

- Website: https://www.8starlabs.com
- Contact: hello@8starlabs.com
- Related: https://www.8starlabs.com/llms.txt, https://www.8starlabs.com/sitemap.xml

## Principles

- Carefully curated: ship fewer things, finished. Every surface is intentional.
- Thoughtful design: clarity over decoration. Generous whitespace, calm contrast.
- Reliable engineering: accessible, themeable, and consistent by construction.
- Quiet by default: neutral palette, restrained motion, content leads.

## Color

Colors are defined as OKLCH CSS custom properties in app/globals.css and exposed
to Tailwind via @theme. The palette is intentionally neutral; semantic roles —
not raw hues — are referenced throughout the UI. Every token has a light and dark
value so all surfaces are theme-aware.

### Light theme

- background: oklch(1 0 0)
- foreground: oklch(0.145 0 0)
- primary: oklch(0.205 0 0)
- primary-foreground: oklch(0.985 0 0)
- secondary: oklch(0.97 0 0)
- muted: oklch(0.97 0 0)
- muted-foreground: oklch(0.556 0 0)
- accent: oklch(0.97 0 0)
- destructive: oklch(0.577 0.245 27.325)
- border: oklch(0.922 0 0)
- ring: oklch(0.708 0 0)
- surface: oklch(0.98 0 0)

### Dark theme

- background: oklch(0.145 0 0)
- foreground: oklch(0.985 0 0)
- primary: oklch(0.922 0 0)
- primary-foreground: oklch(0.205 0 0)
- secondary: oklch(0.269 0 0)
- muted-foreground: oklch(0.708 0 0)
- destructive: oklch(0.704 0.191 22.216)
- border: oklch(1 0 0 / 10%)
- surface: oklch(0.2 0 0)

### Usage

- Use semantic tokens (bg-background, text-foreground, bg-primary, text-muted-foreground)
  rather than literal colors so light/dark stays automatic.
- Pair every background token with its matching `-foreground` token for contrast.
- Reserve `destructive` for irreversible or error states only.

## Typography

- Primary typeface: Inter, with the system sans stack as fallback
  (-apple-system, system-ui, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif).
- Monospace: var(--font-mono) for code, titles in code blocks, and inline tokens.
- Scale: Tailwind's default type scale (text-sm through text-4xl+). Body copy is
  set in text-sm/text-base; headings step up with deliberate `mt` rhythm.
- Tone: sentence case, concise labels, no shouting.

## Shape & spacing

- Base radius: --radius = 0.625rem. Derived tokens: sm = radius - 4px,
  md = radius - 2px, lg = radius, xl = radius + 4px.
- Spacing follows Tailwind's --spacing unit; layout favors generous whitespace.
- Header height: --header-height = calc(var(--spacing) * 14).

## Motion

- html { scroll-behavior: smooth } for in-page anchor navigation.
- Animations via tailwindcss-animate; transitions are short and subtle.
- Respect user intent: motion is supportive, never required to understand content.

## Theming

- Mode is class-based (`.dark`) and managed by the local ThemeProvider
  (attribute="class", defaultTheme="system", enableSystem), with an early
  document script setting the initial class before hydration.
- Never hardcode hex/rgb in components; consume CSS variables or Tailwind tokens.

## Components

UI is built on shadcn/ui (Radix primitives) with custom and MagicUI extensions.
Component sources live under /components:

- components/shadcn — Radix-based primitives (button, dialog, select, tooltip, ...).
- components/8starlabs-ui — brand-specific composite components.
- components/magicui — motion and visual-flair components.
- components/custom — one-off product components.
- components/layout — site header, footer, and shell.

Conventions:

- Accessibility comes from Radix primitives; preserve roles, focus, and labels.
- Variants are expressed with class-variance-authority, not ad-hoc class soup.
- Compose with the `cn` utility (clsx + tailwind-merge) to merge classes safely.

## Voice

- Calm, precise, understated. Describe the product, skip the hype.
- Prefer concrete nouns and verbs over adjectives.
- Match the brand promise: curated, thoughtful, reliable.

## Discoverability

- https://www.8starlabs.com/design.md — this document
- https://www.8starlabs.com/llms.txt — site overview for language models
- https://www.8starlabs.com/sitemap.xml — full URL inventory
- https://www.8starlabs.com/robots.txt — crawl directives