Marketing site · Documentation · Live UI kit

---

This folder is a reusable design-system starter for future projects. It is intentionally product-agnostic: swap the project name, brand colors, logo assets, sample data, and domain terms before using it in production.

The template is optimized for fast project starts:

• A clear design-system README with replaceable decisions.
• A Codex/Claude-style SKILL.md entrypoint for invoking the design guidance.
• Shared CSS tokens in colors_and_type.css.
• Small preview cards in preview/ for colors, typography, spacing, and components.
• A static React UI kit in ui_kits/desktop/ that runs directly from index.html.

What's Inside

Path	Purpose
README.md	This file. General usage, design rules, and customization checklist.
SKILL.md	Agent skill entrypoint for using this template in future design/build tasks.
colors_and_type.css	Canonical design tokens — colors, fonts, spacing, radius, shadows — plus base typography and the .card utility.
assets/	Replaceable brand marks, imagery, and generated assets.
uploads/	Scratch space for source files attached during a working session.
preview/	Small standalone HTML cards for reviewing tokens and component examples. They @import colors_and_type.css so the palette stays unified.
site/	Four-page marketing site that promotes the system and uses it as a working specimen.
ui_kits/desktop/	Static React click-through with a sidebar, dashboard, workflow board, data table, and assistant panel. See its own README.md for file-by-file notes.

Palette

Warm-neutral surfaces, one reserved primary, five accents for differentiation, four status colors. Tune them in colors_and_type.css — the preview cards and the marketing site read from the same file.

Full token reference

Token	Default	Notes
--color-bg	#ede5cc	Page background.
--color-surface	#f5efd8	Default card / panel surface.
--color-surface-soft	#faf6e6	Hover / selected-row surface — between --color-surface and white.
--color-surface-alt	#e0d5b8	Secondary surfaces, subdued buttons.
--color-surface-deep	#cfc2a3	Third sand tier — dividers in dark sections, slider tracks, muted fills.
--color-surface-strong	#ffffff	Inputs, focused fields, contrast surfaces.
--color-text	#141413	Primary text.
--color-muted	#5e5d59	Secondary text.
--color-subtle	#87867f	Captions, helper text.
--color-primary	#9e3728	Reserved accent — primary actions, active states.
--color-primary-soft	#b8432f	Slightly lighter accent for illustrative use.
--color-error	#b53333	Hard error / blocked state — distinct from --color-primary.
--color-focus	#3898ec	Focus ring color.

Two useful elevation tokens exist but aren't required: --shadow-ring (a 1px ring used in place of a heavier shadow) and --shadow-soft (a soft drop shadow for elevated cards / overlays).

Note: --color-danger-fg defaults to the same value as --color-primary. That keeps the warm-neutral palette tight, but products with a strong "do not click this in error" surface should rebind it to --color-error or to a dedicated brand-aligned hue.

Accent family — usage rules

The accent tokens are non-primary colors for differentiation — chart series, taxonomy tags, illustrations, decorative moments. They are deliberately not interactive colors: reserve --color-primary for the single most important action on any screen.

Token	Default	Use For
--color-accent-teal	#2c5862	Warm/cool counterweight to the primary. Strong chart-series color, "data" or "analytics" surfaces, secondary brand moments.
--color-accent-slate	#5a6b78	Palette-native alternative to the bright --color-focus blue. Chart axes, informational pills, secondary links, neutral-cool moments.
--color-accent-ochre	#b8862b	"Featured," "premium," or starred-item accents. Chart series next to primary and teal. Richer than --color-warning-fg.
--color-accent-olive	#6b7242	Neutral category color that does not read as success. Taxonomy tags, third chart-series.
--color-accent-plum	#6b3f4f	Third tag color when sage and ochre are taken. Warm-purple that sits cleanly against parchment without competing with the primary.

Discipline rule: if a screen needs more than three accents at once, the design is asking too much of color. Reach for typography, spacing, or iconography instead.

See preview/colors-extended.html for live swatches and recommended pairings.

Typography

One serif, one sans, one mono — three jobs. Lora handles editorial moments. Inter does the heavy UI lifting. JetBrains Mono shows up for IDs, code, timestamps, and dense metrics. Use one or two typefaces in a real project unless the brand has a strong reason for more.

First Use Checklist

1. Replace the Hearth UI wordmark in ui_kits/desktop/Sidebar.jsx and the <title> in ui_kits/desktop/index.html with the real product or client name.
2. Replace the placeholder logo in ui_kits/desktop/ProductLogo.jsx and update the brand mark preview in preview/brand-logo.html.
3. Put real brand assets in assets/ and remove unused sample assets.
4. Tune the color tokens in colors_and_type.css — that file is the single source of truth, and preview/_card.css reads from it.
5. Rename the navigation entries in Sidebar.jsx (Dashboard, Projects, Workflow, Calendar, People, Library, Resources, Billing, Reports) to match the real product surface.
6. Replace sample data in ui_kits/desktop/*.jsx — account names (ACME Studio, Northwind Labs, ...), project ids (PRJ-2026-XXXX), the Alex M. / admin profile in the sidebar footer, and the v0.1.0 · Starter version pill.
7. Delete screens or preview cards that do not match the project (the assistant panel and the resource table are the most likely cuts).
8. Update SKILL.md frontmatter (name, description) so the agent invocation matches the real project.
9. Add project-specific implementation notes once the target stack is known.

Design Defaults — personality, content, layout, motion, accessibility

These defaults are deliberately conservative. They give a project a polished starting point without locking it into a narrow brand personality.

Product Personality

Use this template when the product should feel:

• Clear and operational.
• Warm but not decorative.
• Useful before it is flashy.
• Mature enough for repeated daily use.

If the project needs a stronger personality, treat these defaults as scaffolding and rewrite the copy, color, typography, and motion rules around the real audience.

Content

• Prefer concrete labels over marketing language.
• Use Title Case for navigation, page titles, section headers, and button labels.
• Use sentence case for helper text, empty states, and longer descriptions.
• Avoid emoji in product UI unless the product voice explicitly calls for it.
• Keep empty states practical: what happened, what to do next.
• Name sample data generically: ACME Studio, Northwind Labs, PRJ-2026-001.

Layout

• Use an 8px base spacing scale.
• Keep dense tools compact but not cramped.
• Favor tables, lists, tabs, segmented controls, and sidebars for operational products.
• Use cards for individual repeated items, modals, and framed tools.
• Avoid nesting cards inside cards.
• Keep dashboards scannable: metrics first, workflow next, recent activity last.

Borders, Radius, And Elevation

• Standard border: 1px solid var(--color-border).
• Default card radius: 8px.
• Default button radius: 8px to 12px.
• Use ring shadows before heavy drop shadows.
• Reserve large radius and heavier elevation for modals, overlays, and featured content.

Motion

• Default transitions: 150ms ease for color and background changes.
• Modals and overlays: short opacity fade.
• Avoid novelty motion in tools people use repeatedly.

Accessibility

• Keep focus states visible.
• Use real buttons and inputs for interactive controls.
• Do not rely on color alone for status.
• Check table layouts at narrow widths before shipping.
• Replace placeholder contrast pairs if the brand palette changes.

Color Rules

The default palette is warm-neutral with one reserved accent. It is a good starting point for admin tools, desktop apps, B2B dashboards, and internal systems.

• Keep page backgrounds calm.
• Reserve the primary accent for important actions and active states.
• Use semantic status colors sparingly and consistently.
• Do not let sample colors become accidental brand decisions.

How to Adapt This Template

For a SaaS/admin product, keep the sidebar/dashboard structure and tighten the density.

For a marketing site, keep the tokens and typography, but build a real first-viewport hero with product imagery.

For a game or playful app, replace the palette, type, and motion guidance. The operational defaults here will feel too restrained.

For a mobile app, keep tokens and component language, but rebuild layouts around native navigation patterns.

Static UI Kit

Open ui_kits/desktop/index.html in a browser. It loads React, ReactDOM, and Babel from CDNs, then renders the sample screens with no build step.

Implemented surfaces: Dashboard (metric cards, overview band, recent activity table), Workflow Board (kanban-style project stages), Resource Table (inventory/data table with status badges), Assistant Panel (support/chat overlay).

The kit is intentionally plain JSX and inline styles so it can be copied into prototypes quickly. For production apps, port the ideas into the target component system rather than shipping these files directly.

Preview Cards

The preview/ folder contains standalone HTML cards for quick review. Each one opens directly in a browser and references the canonical token file.

Use them as references for colors, type scale, spacing, radius and elevation, components (buttons, cards, inputs, sidebar), and iconography rules.

Asset Policy

Everything in assets/ is replaceable. For a real project:

• Add the final logo source files.
• Keep raster exports alongside editable vector or source files.
• Name assets by role, not by temporary brand experiments.
• Remove assets that belong to previous projects.