Guidelines

Design

Guidelines v1.2.0

Gray canvas, scarce honey gold, evidence over decoration. This page is the visual handbook. Agents should fetch the lean markdown - not this HTML.

Download markdown Brand assets

For agents

This HTML page is the human handbook. Do not scrape it. Fetch the lean composition file, then load skills/design-md/SKILL.md. 

# 1. Fetch the composition file
https://shellui.com/design.md

# 2. Then load the topic skill from this repo
skills/design-md/SKILL.md

Color

Each swatch shows light on the left and dark on the right. Values come from src/_data/designTokens.js and must match input.css.

Accent

Honey gold is the action color, not a wash. Use it on the primary button, the product eyebrow, and key links.

  • Light #e3a512
    Dark #e8b84a

    primary

    Accent / buttons

    #e3a512 #e8b84a

  • Light #1a1408
    Dark #1a1408

    primary-foreground

    Text on gold

    #1a1408 #1a1408

  • Light #c4920a
    Dark #e8b84a

    primary-ink

    Gold text on light; in dark use primary

    #c4920a #e8b84a

  • Light #e3a512
    Dark #e8b84a

    ring

    Focus

    #e3a512 #e8b84a

Canvas

Pages sit on a gray field. Light and dark are both first-class.

  • Light #ffffff
    Dark #030712

    background

    Page canvas

    #ffffff #030712

  • Light #111827
    Dark #f9fafb

    foreground

    Primary text

    #111827 #f9fafb

  • Light #f9fafb
    Dark rgb(255 255 255 / 0.05)

    muted

    Quiet wells

    #f9fafb white/5

  • Light #4b5563
    Dark #9ca3af

    muted-foreground

    Secondary text

    #4b5563 #9ca3af

Structure

Earn a border or raised surface when spacing cannot express the grouping.

  • Light #e5e7eb
    Dark #1f2937

    border

    Rules, cards

    #e5e7eb #1f2937

  • Light #ffffff
    Dark #111827

    card

    Raised surface

    #ffffff #111827

  • Light #111827
    Dark #f9fafb

    card-foreground

    Text on card

    #111827 #f9fafb

Type

System font stack. Sentence-case headings. One h1. Rewrite before shrinking the measure.

Page title

Build the app

text-4xl font-bold md:text-5xl

Section

Shared authentication

text-2xl / text-3xl font-semibold tracking-tight

Lede

The shell wraps your app with navigation, auth, admin, and storage.

text-lg text-muted-foreground

Body

Lead with what ships today. Keep AI, MCP, and marketplace chrome quiet unless the page is about that surface.

text-base/7

Label

Developers

text-sm font-medium

Mono

bg-primary text-primary-ink

font-mono text-xs

Shape and space

Controls are tighter than cards. Vertical rhythm comes from heading-to-body proximity and larger gaps at section turns.

Radius

  • rounded-sm

    0.25rem · Tight chips

  • rounded-md

    0.375rem · Buttons and controls

  • rounded-lg

    0.75rem · @theme radius-lg

  • rounded-xl

    0.75rem · Cards and wells

Spacing

  • px-4

    Page padding (mobile)

  • px-6

    Page padding (sm)

  • px-8

    Page padding (lg)

  • mt-10

    Section step

  • mt-16

    Larger section turn

Actions

One primary button. The secondary is a text link. Gold stays scarce.

Get started View on GitHub Guidelines Hover Focus

Surfaces

The page is one continuous canvas. These islands lock light and dark tokens so you can compare them without toggling the site theme.

light

Shellui

Shared authentication

The shell wraps the app with sign-in, admin, and storage so you can ship the product.

Get started View on GitHub →

Config

shellui.config.ts

Quiet well · muted

dark

Shellui

Shared authentication

The shell wraps the app with sign-in, admin, and storage so you can ship the product.

Get started View on GitHub →

Config

shellui.config.ts

Quiet well · muted

Composition

Start with the reader's job. The first viewport is the argument. Reuse layouts already in this repo before inventing a kit.

  • Reader first

    Identify what they need to understand or decide, the strongest supported answer, and the evidence that earns it.

  • One focal relationship

    Surround it with a few supporting objects and enough open space. Equal-weight blocks mean redesign.

  • Reuse Plus patterns

    Centered hero, feature split, two-tier pricing, FAQ list, quiet CTA band. Restyle with these tokens. Soft primary/amber ambient on the homepage hero is allowed.

  • What ships today

    Iframe host, SDK, auth, admin, storage, Files. Keep AI and marketplace chrome quiet unless the page is about that surface.

Do and don't

Same material, two compositions. The left reuses the shipped dual-CTA opening. The right is the generic grid this system rejects.

Do

One claim, one primary action, gray canvas, scarce gold. Soft primary ambient behind the hero is brand warmth.

Shellui

Build the app, not the infrastructure

Shared auth, admin, and storage around your iframe app.

Get started GitHub →
Don't

Equal-weight cards, gold headings, and banned marketing words.

Unlock the platform

Auth

Seamless. Easy.

Admin

Seamless. Easy.

Storage

Seamless. Easy.

AI

Seamless. Easy.