Wisteria Craft Design Language¶

The unified visual language for the Loryth platform across three surfaces: the cross-platform app (React web + React Native), the marketing website, and the documentation site (MkDocs Material).

Philosophy¶

Craft over convenience. Wisteria Craft embraces the ethos of self-hosting: deliberate choices, artisanal attention to detail, and pride in building something that's truly yours. The palette draws from natural dye traditions — deep wisteria purples that feel hand-mixed, warm amber tones that evoke beeswax and candlelight. Typography balances character (serif headings) with clarity (humanist sans body text). The system feels handcrafted without sacrificing professionalism.

Color Palette¶

Primary: Wisteria Purple¶

A rich, Tailwind-standard purple scale used as the primary brand color across all surfaces.

Secondary: Artisan Amber¶

Warm gold/amber for accents, calls-to-action, and warmth. Think aged brass, honey, handmade candles.

Semantic Colors¶

Desaturated to avoid competing with the brand palette.

Neutrals: Slate¶

Cool-toned neutrals for backgrounds, text, and structural elements.

Surface Tokens¶

Light Mode¶

Dark Mode¶

Typography¶

Font Families¶

Type Scale¶

Based on a major third ratio (1.250). All values in rem (1rem = 16px).

Font Weights¶

Line Heights¶

Spacing¶

Base unit: 4px (0.25rem). All spacing values are multiples of 4px.

Component Spacing Defaults¶

Border Radii¶

Soft and organic, but not overly rounded. No hard edges.

Shadows¶

Soft, warm shadows. Elevation conveys depth without harshness.

Light Mode¶

Uses slate-900 (rgba(15, 23, 42, ...)) as shadow color for natural, warm shadows.

Dark Mode¶

Shadows become wisteria-tinted glows for a warm, dimensional feel.

Interactive Glows (Dark Mode)¶

For buttons, focus states, and interactive elements:

Special Touches¶

These signature elements create visual cohesion across all three surfaces.

Grain Texture¶

A barely-visible noise texture applied to large background areas (hero sections, dark mode backgrounds) to add warmth and break up flatness.

• Light mode hero sections: opacity: 0.03
• Dark mode backgrounds: opacity: 0.05

Iconography¶

Rounded, friendly, slightly organic stroke icons. Use Lucide as the base icon set with a stroke width of 1.75px for a softer feel. For accent icons on the marketing site, pair amber icons with wisteria text.

Interactive States¶

All clickable elements follow a consistent state progression:

Transition: 150ms cubic-bezier(0.4, 0, 0.2, 1) (ease-out).

Inline Code Styling¶

Inline code uses amber-tinted backgrounds for a warm, distinctive look:

• Light mode: background: amber-100 (#fef3c7), color: amber-800 (#92400e)
• Dark mode: background: amber-950 (#451a03), color: amber-200 (#fde68a)

Surface: App (React Web + React Native)¶

The app is the primary product surface — functional, calm, and optimized for daily use.

Characteristics¶

Navigation¶

• Sidebar: slate-100 (light) / slate-900 (dark) background
• Active state: purple-600 / purple-400 indicator
• Icons: Lucide at 1.75px stroke

Data Display¶

• Tables: zebra striping with slate-100 / slate-200 (light) or slate-900 / slate-800 (dark)
• Form inputs: slate-200 (light) / slate-800 (dark) background, shadow-inner on focus

Surface: Marketing Website¶

The website needs to inspire, communicate values, and convert visitors.

Characteristics¶

CTA Buttons¶

• Primary: amber-500 background with purple-600 text/border
• Hover: amber-600 with wisteria glow (dark mode)
• The amber CTAs paired with wisteria headings create a distinctive pairing

Hero Section¶

• Grain texture on background (opacity: 0.05)
• Fraunces headings at large sizes
• Generous whitespace above and below

Illustrations¶

Duotone illustrations using purple-600 + amber-400. Hand-drawn aesthetic — artisanal tools, servers in a workshop, cables as vines.

Surface: Documentation (MkDocs Material)¶

Documentation prioritizes readability, scannability, and focus.

Characteristics¶

Fraunces Usage¶

Only for the site title and major section dividers. All content headings use Inter to maintain focus on readability.

Admonitions¶

Style: 4px left border with tinted background.

Code Blocks¶

• Background: slate-900 (light mode, dark block) / slate-950 (dark mode)
• Syntax highlighting with purple and amber accents
• JetBrains Mono at sm (14px) for inline code, base (16px) for blocks

Sidebar¶

• Active item: purple-600 / purple-400 left border (3px) with subtle background tint
• Hover: lighter purple background tint

MkDocs Material Theme Configuration¶

theme:
  name: material
  palette:
    - scheme: default
      primary: custom
      accent: custom
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - scheme: slate
      primary: custom
      accent: custom
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  font:
    text: Inter
    code: JetBrains Mono

Custom CSS overrides (stylesheets/wisteria-craft.css):

[data-md-color-scheme="default"] {
  --md-primary-fg-color: #7c3aed;        /* purple-600 */
  --md-accent-fg-color: #f59e0b;         /* amber-500 */
  --md-default-bg-color: #ffffff;
  --md-default-fg-color: #0f172a;        /* slate-900 */
}

[data-md-color-scheme="slate"] {
  --md-primary-fg-color: #a78bfa;        /* purple-400 */
  --md-accent-fg-color: #fbbf24;         /* amber-400 */
  --md-default-bg-color: #0f172a;        /* slate-900 */
  --md-default-fg-color: #f1f5f9;        /* slate-100 */
}

h1, h2, h3, h4, h5, h6 {
  font-family: "Inter", sans-serif;
  font-weight: 600;
}

/* Inline code: amber-tinted */
code {
  background-color: #fef3c7;             /* amber-100 */
  color: #92400e;                        /* amber-800 */
  border-radius: 4px;
  padding: 2px 6px;
}

[data-md-color-scheme="slate"] code {
  background-color: #451a03;             /* amber-950 */
  color: #fde68a;                        /* amber-200 */
}

Diagram Colors¶

For Mermaid diagrams, use the following standardized palette (compatible with dark mode styling):

Dark mode diagram styling:

classDef wisteria fill:none,stroke:#a78bfa,stroke-width:2px,color:#a78bfa
classDef amber fill:none,stroke:#fbbf24,stroke-width:2px,color:#fbbf24
classDef success fill:none,stroke:#86efac,stroke-width:2px,color:#86efac
classDef info fill:none,stroke:#93c5fd,stroke-width:2px,color:#93c5fd
classDef error fill:none,stroke:#fca5a5,stroke-width:2px,color:#fca5a5

Cross-Surface Cohesion Summary¶

What stays consistent across all three surfaces:

1. Wisteria purple + artisan amber as the two brand colors
2. Fraunces serif for display headings (adapted per surface)
3. Inter for body text everywhere
4. JetBrains Mono for all code
5. 4px base spacing unit with the same scale
6. Craft ethos: grain textures, rounded Lucide icons, warm shadows
7. Amber inline code styling — a distinctive signature
8. Purple-tinted glows in dark mode instead of harsh drop shadows
9. Consistent interactive states (hover, active, focus progression)

What varies per surface: