# Brand (v2.0.0)

https://shellui.com/guidelines/brand.md

Brand is identity: name, one-liner, logo, color summary, and production files. Token numbers live in [Foundations](/guidelines/foundations/). Print grid and Pantone live in [Print](/guidelines/print/). Voice and punctuation live in [Writing](/guidelines/writing/).

## Name and one-liner

- Product name: **Shellui** only. Never "The Host". Never raise the last two letters or camel-case the name in prose (`@shellui/sdk` and repos stay lowercase).
- Default one-liner: Shellui is an open-source web app development platform: a microfrontend shell that wraps your application with shared navigation, authentication, storage, and administration.
- In prose, "the shell" (lowercase) is the running host around the iframe app.

## Logo

- Use official files from [Downloads](#downloads). Wordmark and S mark ship in ink, white, and gold (SVG and PNG).
- Measure clear space from the logo itself, not the file bounds. Minimum wordmark width 72 px / 18 mm; below that, use the mark.
- Do not redraw, recolor, stretch, add effects, or build lockups with other marks.
- Do not imply endorsement, sponsorship, or partnership unless it exists.

## Color (summary)

- Brand gold `#E3A512`: fills, rules, logo shapes. Not body text on white.
- Text gold `#8A6300` on light backgrounds; `#E8B84A` on dark screens (website dark mode included).
- On gold text `#1A1408` on gold buttons.
- Soft gold wash behind the marketing homepage hero is **web only**. Print and flat export stay flat (see [Print](/guidelines/print/)).

## Voice (summary)

Developers are the audience. Active voice, evidence over slogans, no rhetorical questions. Full rules: [Writing](/guidelines/writing/).

## Downloads {#downloads}

Production files stay at stable URLs under `/brand-assets/` (hotlinked in the kit and docs).

- [Brand kit v1 (PDF)](/brand-assets/shellui-brand-kit-v1.pdf): 33-page brand handbook
- [Brand assets v1 (ZIP)](/brand-assets/shellui-brand-assets-v1.zip): logos, icons, Open Graph images, social banners, email signature

Individual logos, icons, and social templates are listed on this page in the download grid below the prose.

## How to use this file

- **Humans**: `/guidelines/brand/`
- **Agents**: `https://shellui.com/guidelines/brand.md`
- **Hub**: [Guidelines](/guidelines/)


---

# Foundations (v2.0.0)

https://shellui.com/guidelines/foundations.md

Foundations are the shared numbers: color, type, spacing, and radius. Values on this page are generated from [`tokens/tokens.json`](https://github.com/shellui/website/blob/develop/tokens/tokens.json) at build time. If a hex here disagrees with prose elsewhere, trust this page.

- **Web**: Inter on screen (self-hosted on shellui.com). Token utilities in Tailwind (`bg-primary`, `text-primary-ink`, and the rest).
- **Print**: IBM Plex Sans and Plex Mono. See [Print](/guidelines/print/) for grid, folios, and Pantone.
- **Interface**: how to compose pages with these tokens. See [Interface](/guidelines/interface/).

## Downloads

- [tokens.json](/guidelines/generated/tokens.json): W3C Design Tokens source
- [tokens.css](/guidelines/generated/tokens.css?v=683f582c): `:root` variables for light theme

## Color tokens (web)

Brand gold `#E3A512` is for fills, rules, and the logo, not body text. Text gold is `#8A6300` on light backgrounds and `#E8B84A` in dark mode (`primary-ink` remaps automatically).

<!-- tokens:begin -->
| Token | Light | Dark | Role |
| --- | --- | --- | --- |
| `primary` | `#e3a512` | `#e8b84a` | Accent / buttons |
| `primary-foreground` | `#1a1408` | `#1a1408` | Text on gold |
| `primary-ink` | `#8a6300` | `#e8b84a` | Gold text on light; remaps on dark |
| `ring` | `#e3a512` | `#e8b84a` | Focus |
| `background` | `#ffffff` | `#030712` | Page canvas |
| `foreground` | `#111827` | `#f9fafb` | Primary text |
| `muted` | `#f9fafb` | `rgb(255 255 255 / 0.05)` | Quiet wells |
| `muted-foreground` | `#4b5563` | `#9ca3af` | Secondary text |
| `border` | `#e5e7eb` | `#1f2937` | Rules, cards |
| `card` | `#ffffff` | `#111827` | Raised surface |
| `card-foreground` | `#111827` | `#f9fafb` | Text on card |
| radius | `rounded-xl` cards (`0.75rem`); `rounded-md` controls (`0.375rem`) | same | Shape |
<!-- tokens:end -->

## Gold (brand and print)

| Name | Hex | Pantone (coated) | Use |
| --- | --- | --- | --- |
| Brand gold | `#E3A512` | 124 C (7405 U uncoated) | Fills, rules, logo |
| Text gold | `#8A6300` | 4027 C | Links and gold text on light |
| Text gold (dark) | `#E8B84A` | None | Links and gold text on dark |
| On gold | `#1A1408` | None | Text on gold buttons |

Verify coated and uncoated Pantone against a physical swatch before the first print run.

## Typography

| Surface | Family | Notes |
| --- | --- | --- |
| Website and in-shell apps | Inter | Self-hosted, `font-display: swap`, Latin subset |
| Print and PDF kit | IBM Plex Sans | One family for all print words; Plex Mono for code |
| Generated images | Inter | og:image, social banners, icons (not print) |

Type scale on the web follows Tailwind defaults already used on shellui.com: page title `text-4xl font-bold md:text-5xl`, section `text-2xl` / `text-3xl font-semibold`, body `text-base/7`, labels `text-sm font-medium`. Print sizes live on [Print](/guidelines/print/).

## Spacing and radius

| Token | Web | Print |
| --- | --- | --- |
| Outer gutters | `.page-x` (`px-4 sm:px-6 lg:px-8`) | 20 mm page margin |
| Below header | `.page-top` | Running head only on body pages |
| Section step | `mt-10`, `mt-16` | 6 mm stacked cards, 8 mm feature gaps |
| Controls | `rounded-md` (`0.375rem`) | 2 mm radius on frames |
| Cards | `rounded-xl` (`0.75rem`) | 2 mm on screenshot frames |

## Motion

Honor `prefers-reduced-motion`. Animate `transform` and `opacity` only, never `transition: all`. Marketing theme reveal already disables under reduced motion; match that in product UI.


---

# Writing guidelines (v2.0.0)

https://shellui.com/guidelines/writing.md

These rules cover copy on [shellui.com](https://shellui.com), [docs.shellui.com](https://docs.shellui.com), and in-product strings that developers read. Lead with what Shellui ships today: a microfrontend shell with shared navigation, authentication, administration, and storage. Keep AI, MCP, and marketplace ideas quiet unless the page is actually about that surface.

Agents: load this file. Do not scrape the HTML page. The `version` field in the frontmatter is the public "Guidelines v…" label.

## How to use this file

- **Humans**: read the page at `/guidelines/writing/`, or download this markdown
- **Agents**: read `content/guidelines/writing.md` in this repo, or fetch `https://shellui.com/guidelines/writing.md`
- **Skill wrapper**: `skills/writing-guidelines/SKILL.md`
- **Sibling**: [Interface](/guidelines/interface/) for UI, accessibility, and chrome
- **Compose pages with**: [design.md](/design.md) (`fetch https://shellui.com/design.md`) or [interface.md](/guidelines/interface.md)
- **Hub**: [Guidelines](/guidelines/)

Review files against every rule below. Output concise, high-signal findings. Sacrifice grammar for brevity.

## Brand

- The product name is **Shellui** only. Never "The Host". Never raise the last two letters or camel-case the name; packages and repos stay lowercase (`@shellui/sdk`, `shellui/identity-service`)
- In prose, "the shell" (lowercase) is the running host around the iframe app. That is a common noun, not a second brand
- Default one-liner: Shellui is an open-source web app development platform: a microfrontend shell that wraps your application with shared navigation, authentication, storage, and administration (defined once in [Brand](/guidelines/brand/))
- Audience is developers shipping a product inside that shell, not generic "users" or "teams exploring AI"
- Surfaces: [docs.shellui.com](https://docs.shellui.com) for docs, [playground.shellui.com](https://playground.shellui.com) to try it, [GitHub](https://github.com/shellui) for source. Mention [shellui.ai](https://shellui.ai) only when the page is about that property
- Logo usage lives on [Brand](/guidelines/brand/) only. Do not mix logo rules into product docs

## Voice and tone

- Active voice. Mental test: append "by monkeys". If the sentence still parses, rewrite
- Direct address: `you`, never `the user` or `one can`
- Imperative for steps: "Call **init**", not "You will need to call **init**"
- Target sentences under 20 words
- Contractions are fine (`you'll`, `it's`)
- Present tense unless you are describing behavior that does not exist yet
- Limit `we`: only for a deliberate Shellui action ("we recommend", "we deprecated"), never as a stand-in for "you"
- No rhetorical questions (reads as marketing)
- Second-read test: read each sentence once at speech pace. If you re-read to parse it, name the subject, the action, and the consequence. Kill metaphor verbs and pronouns that reach back several sentences
- Developer-facing, not salesy. Evidence over slogans. Name the API, file, or command

### Tone, by content type

- **Tutorial**: warm, predictable structure, no traps
- **How-to**: terse, direct (the reader is mid-task)
- **Reference**: neutral, exhaustive, quotable
- **Conceptual**: explain like the reader will teach it back; examples welcome
- **Troubleshooting**: acknowledge the failure, then fix it. Empathy without apology
- **Website / blog**: same voice as docs. Lead with the shipping product, not the roadmap

### Banned words

- `easy`, `simple`, `quick`: puts pressure on the reader and reads as marketing. Replace with a concrete description ("one command", "default settings", "most projects don't need this")
- `very`, `just`, `really`, `simply`: filler; cut or rewrite
- `seamless`, `robust`, `powerful`, `next-generation`, `unlock`, `leverage`: marketing fog; name the behavior
- Do not tease unreleased AI, MCP, app-store, or marketplace work on pages about the shell, auth, admin, or storage

### Concision

- Earn every detail: cut a number, name, or implementation detail if a more general phrasing would not change the reader's understanding or action
- Weasel words: replace vague qualifiers (`significantly`, `many`, `often`, `typically`, `generally`) with a specific number or claim
- Vague quantifiers: no `near-zero`, `sub-second`, `most requests` without a figure you can stand behind
- Filler or metaphor verbs: name the action (`moves through`, `lands`, `carries`, `hits` → the literal step)

### AI-generated tells (flag these)

- Summary-style transitions: never open a paragraph by recapping the last one (`With this setup complete…`, `Now that we've explored…`). Pivot to the next point
- Stop-start sentences: don't split one dependent idea into choppy fragments (`Previously this was manual. Now it's automatic. This saves time.` → one sentence). Short sentences for emphasis are fine
- Spec-sheet voice: rewrite sentences that read like a datasheet (`provides`, `is configurable`, `is explicitly labeled`)
- Cold-open paragraphs: a body paragraph whose first sentence works as a standalone heading has no antecedent. Carry the prior subject forward (`Because…`, `Once…`)
- Personified artifacts: machines don't perform human-physical actions (`hand the browser a URL` → `the browser fetches the URL`; `the token holds…` → `the token is stored…`)
- Reused framing: the angle must come from this page, not a template (`The question most teams face is whether…`)

## Structure and formatting

Rules for how a page is planned, titled, and marked up.

### Planning and content type

- Every docs page has a plan (overview, goal, audience, content plan, open questions) referenced or linked
- Content type declared when the docs system supports it: `Tutorial`, `How-to`, `Reference`, `Conceptual`, `Troubleshooting`, or `Landing`
- Title is user-shaped (the reader's question), not feature-shaped (the engineer's name)
- Page does one job: tutorial or how-to or reference, not three at once
- Goal is verb-driven: "configure", "explain", "debug" (testable)
- Multi-audience pages: short shared opener, then technical subsections
- Website marketing pages still need a one-paragraph opener that states what the page is for

### Headings

- Sentence case for page headings (`H1` `H2` `H3`): "Configure the iframe SDK", not "Configure The Iframe SDK"
- Title case for nav labels: "Writing Guidelines"
- `meta.title` (or the page `title`) becomes the `H1`; nav labels stay short
- Subheadings descriptive, not cute: "Caveats when hosting on a custom domain", not "Caveats"
- The reader should guess the section from the heading alone

### Page structure

- Every page opens with a one-paragraph TL;DR of what it covers
- Every major section opens with a summary sentence
- Spell out acronyms on first use: "JSON Web Key Set (JWKS) is how the shell verifies tokens"
- Define every term the first time you use it (link to its conceptual page when one exists)
- Reference docs organized by surface; education docs organized by reader task
- Keep paragraphs to 2 to 4 sentences. Split anything longer or covering two ideas

### Lists

- Three or more list-shaped items in a paragraph: convert to a list
- Bulleted for unordered; numbered for ordered (lifecycles, sequential steps)
- Always introduce a list with a colon
- No periods at the end of list items unless they are full sentences
- Bold/description format: `- **Term**: description here` (colon after the bold term)

### Code

- Code blocks need a language tag for syntax highlighting
- TypeScript is the default for new examples unless the surface is another language (Python for identity-service, bash for CLI)
- Multi-step flows should show structure (numbered steps, or separate blocks with prose between them)
- Highlight load-bearing lines when the renderer supports it
- ≤80 columns per line in snippets
- ≤25 lines per snippet; split longer blocks with prose
- Omit defaults; don't repeat variable definitions, use a shared name
- Minimal comments in code blocks; prefer prose
- Explain what every code block does in prose (don't drop and run)
- Don't point at a full example file at the end of a guide ("See `app.ts`"); the guide is the deliverable
- Prefer real Shellui names: `shellui.config.ts`, `@shellui/sdk`, `init`, identity-service, storage-service

```typescript
import { init } from "@shellui/sdk";

await init({
  clientId: your_client_id_here,
});
```

### Placeholders

- Text placeholders: `snake_case`, descriptive: `your_access_token_here` (so the reader can double-click to select before pasting)
- Number placeholders: count up `1234567890123` (recognizable as fake, predictable)
- Never angle-bracket tokens, `xxx`, `your-token`, or generic ALL_CAPS

### Data sizes and units

- Space + uppercase unit: `64 KB`, `5 KB`, `200 ms`
- Exception: seconds is bare: `30s`
- Stay consistent so readers can scan

### Pricing pages

- Shellui is MIT-licensed and free to run. Say that plainly
- If you mention paid help, say what it is (architecture, custom work, support) and what it is not
- Never imply a hosted plan or usage meter that does not exist
- Tables when you compare options; don't assume the reader knows the model

### Emphasis

- **Bold** means a UI element or a critical fact, never emphasis-for-emphasis-sake
- If you reach for bold for tone, the sentence is weak; rewrite it
- `Inline code` for paths, file extensions, identifiers, short snippets: `/admin`, `.tsx`, `init`, `shellui.config.ts`
- Rule: if it would look weird without a monospace font, monospace it

### Punctuation and typography

- Prefer a hyphen `-` for a pause or break in prose: "Keep chrome in the shell - layouts, toasts, and theme included."
- Ban em dashes (`—`) and en dashes (`–`) used as punctuation. Do not "fix" ordinary hyphens
- Hyphens in compound words, package names, and flags stay: `microfrontend`, `identity-service`, `--serve`
- Straight quotes in markdown source (`"` `'`). Don't convert to curly quotes by hand
- Ellipsis `…`, not three dots `...`
- Loading states end with `…`: `Loading…`, `Saving…`
- `&` over "and" only where space is tight (nav labels, buttons)

### Source formatting

- Don't hard-wrap paragraphs: each paragraph is one line in source, let the editor wrap
- One blank line before headings; one blank line before and after code blocks
- No `---` horizontal rules between sections
- No extra blank lines between elements that aren't paragraph breaks

### Links

- Define every term the first time it appears; link to its conceptual page when one exists
- Anchor text names the destination; never bare URLs or `here` / `link`
- Canonical docs: [docs.shellui.com](https://docs.shellui.com)
- Playground: [playground.shellui.com](https://playground.shellui.com)
- Source: [github.com/shellui](https://github.com/shellui)
- Brand files: [shellui.com/brand-assets](https://shellui.com/brand-assets/)
- Brand kit and rules: [shellui.com/guidelines/brand](https://shellui.com/guidelines/brand/)
- Do not invent dashboard deep links. Link to the real path (`/admin`, docs page, GitHub repo)

## What to mention (and what to skip)

- **Default to shipping**: iframe host, `@shellui/sdk`, identity-service, admin at `/admin`, storage-service, Files
- **Skip unless the page is about it**: AI features, MCP, an app store, a marketplace, unreleased roadmap items
- **Roadmap pages** may list upcoming work. Everywhere else, upcoming work is a footnote, not the lede
- Don't frame Shellui as an AI platform. It is a shell around your app

## Review

How drafts get checked - by a person or an agent.

### AI workflow

- You are accountable for the content you produce, however it is created
- You are the final arbiter; the model proposes, you dispose
- Hold technical accuracy to a high standard: docs are also consumed by LLMs, and wrong docs train wrong models
- Follow `AGENTS.md` and this file before generating website or docs prose
- Plan first; the plan is the spec the model works against
- After a draft, test: "given this page's goal, can a reader (or a model) complete the task using only this page?"
- Final human review always
- Disclose the model in the PR when the draft was generated

### Quality checklist (required boxes are non-negotiable)

- **Findability**: the page is linked from nav, docs, or the parent feature page
- **Accuracy**: code samples run; screenshots match the current UI
- **Relevance**: code samples where they help (TypeScript first; Python or bash when that is the surface)
- **Clarity**: opener covers who/what/where/why; prerequisites on tutorials; steps are concrete; recommend the shortest path when several exist
- **Completeness**: limits documented; the content plan's goals are addressed
- **Readability**: nav names scannable and use action verbs; subheadings descriptive; sections start with summaries; code blocks formatted; active voice

### Pull requests

- PR description says what to review and links the preview URL
- Author is accountable, not the reviewer; reviewers can approve with nits
- Suggestion comments for small text fixes; a blocking comment for anything bigger
- Disagreement is fine; reject with a one-line reason and move on

## Anti-patterns (flag these)

- Em dashes (`—`) or en dashes (`–`) used as punctuation
- `easy`, `simple`, `quick` describing reader actions
- Passive voice (apply the "by monkeys" test)
- Title Case in page headings (sentence case in `H1` through `H6`)
- Generic placeholders: angle-bracket tokens, `xxx`, `your-token`, `ABC123`
- Code blocks without a language tag
- JavaScript examples where TypeScript is the convention
- Code blocks over 25 lines without prose between
- Hard-wrapped prose paragraphs (multiple lines for one paragraph in source)
- `---` horizontal rules between sections
- Subheadings that are single generic words: `Overview`, `Caveats`, `Notes`
- Bold used for emphasis instead of a UI element or critical fact
- Page or section without an opening summary
- Three dots (`...`) instead of ellipsis (`…`) in loading copy
- Acronyms used before being spelled out
- Bare unit numbers (`64KB`, `5kb`, `200MS`) instead of `64 KB`, `5 KB`, `200 ms`
- "We" standing in for "you"
- Rhetorical questions
- Filler words: `very`, `just`, `really`, `simply`
- References to "the full example file at the end of the guide" rather than inlining the code
- "Loading..." instead of "Loading…"
- Summary-style transitions recapping the previous paragraph (`With this setup complete…`)
- Stop-start fragments splitting one dependent idea into choppy sentences
- Spec-sheet voice reading like a datasheet (`provides`, `is configurable`, `is explicitly labeled`)
- Cold-open body paragraphs whose first sentence has no antecedent
- Personified artifacts performing human-physical actions (`hand the browser a URL`)
- Reused/template framing not specific to the page (`The question most teams face is whether…`)
- Weasel words instead of a specific claim (`significantly`, `many`, `often`, `typically`, `generally`)
- Vague quantifiers without a figure (`near-zero`, `sub-second`, `most requests`)
- Filler or metaphor verbs instead of the literal step (`moves through`, `lands`, `carries`, `hits`)
- Sentences that need a second read to parse
- Paragraphs over 4 sentences or covering two ideas
- Bare URLs or `here`/`link` as anchor text
- Calling the product "The Host" or any spelling other than Shellui
- Leading a shipping-product page with AI, MCP, or marketplace copy
- Ordinary hyphens flagged as errors (hyphens are preferred)

## Review output

Group by file. Use `file:line` format (clickable in VS Code). Terse findings.

```text
## src/features/apps-and-navigation/index.njk

src/features/apps-and-navigation/index.njk:18 - banned word "easy"
src/features/apps-and-navigation/index.njk:24 - em dash in prose; use a hyphen
src/features/apps-and-navigation/index.njk:31 - "the user" → "you"
src/features/apps-and-navigation/index.njk:47 - placeholder YOUR_TOKEN → your_access_token_here

## src/architecture/index.njk

✓ pass
```

State issue + location. Skip explanation unless the fix is non-obvious. No preamble.


---

# Interface (v2.1.0)

https://shellui.com/guidelines/interface.md

Interface rules cover layout, interaction, and composition on [shellui.com](https://shellui.com), [docs.shellui.com](https://docs.shellui.com), and apps hosted in the Shellui iframe. Pair with [Writing](/guidelines/writing/) for copy and [Foundations](/guidelines/foundations/) for tokens. Lead with the shipping shell: navigation, authentication, administration, storage, light and dark themes. Keep AI, MCP, and marketplace chrome out of the default UI.

Agents: load this file or `/design.md` (stable alias). Do not scrape HTML handbooks. The `version` field in frontmatter is the public "Guidelines v…" label.

## How to use this file

- **Humans**: `/guidelines/interface/`
- **Agents**: `https://shellui.com/guidelines/interface.md` or `https://shellui.com/design.md`
- **Writing**: [writing.md](/guidelines/writing/) for voice, punctuation, and banned words
- **Tokens**: [foundations.md](/guidelines/foundations/) and [tokens.json](/guidelines/generated/tokens.json)
- **Brand logos**: [brand.md](/guidelines/brand/) only
- **Hub**: [Guidelines](/guidelines/)

Review files against every rule below. Output concise, high-signal findings. Sacrifice grammar for brevity.

## Product

Shellui is an open-source web app development platform: a microfrontend shell with shared navigation, authentication, administration, and storage. Audience: developers shipping a product inside that shell.

Precise, calm, direct, technically literate, evidence-led, restrained. Name is **Shellui** only. Never "The Host". In prose, "the shell" (lowercase) is the running host. Lead with what ships today (iframe host, `@shellui/sdk`, identity-service, `/admin`, storage, Files). Keep AI, MCP, marketplace, and app-store chrome quiet unless the page is about that surface.

## Priority (when building pages)

1. Preserve supplied facts, package names, URLs, units, qualifiers, and task constraints.
2. Preserve the host stack: Eleventy 3, Tailwind CSS v4, Tailwind Plus patterns already in this repo, Alpine for light demos, shadcn-compatible CSS variables. No new framework, CSS library, or parallel token system apart from the page-scoped island exception under Stack.
3. Make the reader's question, strongest supported answer, and material evidence immediately clear.
4. Establish Shellui authorship through existing nav/footer chrome, Inter typography, gray canvas, and scarce primary gold.
5. Choose a composition specific to this material. Do not clone an unrelated page as a template.
6. Refine responsive behavior and details without weakening the hierarchy.

Ask questions only when proceeding could change product claims, pricing, security, or CTAs. Otherwise omit the unknown, label it, and proceed.

## Stack

- Templates: Nunjucks in `src/`. Layouts: `base`, `page`, `feature`, `post`, `guidelines`, `guidelines-foundations`.
- CSS: `src/assets/css/input.css` → `/assets/css/site.css?v=780c7d86`. Token values: generated from `tokens/tokens.json` into `src/_data/designTokens.js` and `input.css`.
- JS: Alpine (`src/blocks/`), Plus Elements (`/assets/js/elements.js?v=120ff5b8`), theme toggle (`src/assets/js/site.js?v=0dcc97a2`).
- Islands: one page may lazy-load one React bundle for a single interactive piece it cannot express in Alpine. Source in `src/islands/`, bundled by esbuild with its CSS inlined. Ship a static fallback in Nunjucks and reuse token variables.
- Images: `img/`, logos from [Brand downloads](/guidelines/brand/#downloads). Do not stretch or recolor the wordmark.
- Iframe: site can load in the shell (`@shellui/sdk` tiny). Do not cover host chrome. Theme follows `html.dark`.
- Do not ship a single-file HTML deliverable, a React/Vite rewrite, or a parallel design-system package.

Chrome to reuse: `nav.njk` (fixed `h-16`), `footer.njk`, `logo.njk`. Main padding: `.page-top` (below the fixed header) and `.page-x` (horizontal gutters). Do not add a second header, mega-footer, announcement bar, or extra theme switcher.

## Shellui chrome

The product is a microfrontend shell. The host owns shared chrome; the iframe owns the app.

- Host chrome: sidebar, top bar, or window layout, plus toasts, dialogs, drawers, theme, and language. Do not rebuild those inside the iframe
- Iframe apps talk to the shell with `@shellui/sdk` (`init`, postMessage). Do not reach into host DOM
- Layout mode is a shell concern (`shellui.config.ts`). App UI must work in sidebar, top-bar, and window layouts
- Do not cover the shell header, nav, or toast region. Fixed app bars need an offset for host chrome
- Authentication, admin (`/admin`), and Files are shell surfaces. Deep-link them; don't clone their navigation
- Theme and locale live in the shell. Read them; don't ship a second theme picker in the app unless the app is the settings surface
- Prefer existing Tailwind tokens from [Foundations](/guidelines/foundations/). Primary accent is honey gold (`--color-primary`, `--color-primary-ink`). Do not invent a second brand color
- Marketing site chrome: fixed header (`h-16`), `.page-top` and `.page-x` gutters, footer. Put `.page-x` on the outer band and keep `max-w-*` children unpadded so they align with the header. Sticky in-page UI must clear the header
- Logos and marks: see [Brand](/guidelines/brand/). Do not stretch, recolor, or swap in a different wordmark

## Accessibility and focus

- Icon-only buttons need `aria-label`
- Form controls need a `<label>` or `aria-label`
- Interactive elements need keyboard handlers (`onKeyDown` / `onKeyUp` where click is not enough)
- `<button>` for actions; `<a>` for navigation. Never a `<div>` with a click handler
- Images need `alt` (or `alt=""` if decorative)
- Decorative icons need `aria-hidden="true"`
- Async updates (toasts, validation) need `aria-live="polite"`. Shell toasts already live in the host - use the SDK, don't mount a second live region that fights the host
- Semantic HTML (`header`, `nav`, `main`, `footer`) before ARIA
- Headings hierarchical `h1` to `h6`; one `h1` per page
- Include a skip link to main content on long chrome (shell and marketing header)
- `scroll-margin-top` on heading anchors so the fixed header does not cover the target
- Meaningful media needs captions, transcripts, or descriptions
- Media controls need keyboard support; hide decorative media from assistive tech
- Interactive elements need visible focus: `focus-visible:ring-*` or equivalent
- Never `outline-none` without a focus replacement
- Use `:focus-visible` over `:focus` (avoid a ring on pointer click)
- Group focus with `:focus-within` for compound controls
- Trap focus in dialogs; return it to the trigger on close
- Hit targets: if the visual control is < 24px, expand the hit area to ≥ 24px; on mobile ≥ 44px
- Status is not color alone; include a text label
- Sticky headers, footers, and overlays must not cover the focused element (16 × 4px marketing header; shell top bar in top-bar layout)

## Forms and input

- Inputs need `autocomplete` and a meaningful `name`
- Use the correct `type` (`email`, `tel`, `url`, `number`) and `inputmode`
- Never block paste (`onPaste` + `preventDefault`)
- Labels clickable (`htmlFor` or wrapping the control)
- Disable spellcheck on emails, codes, usernames, tokens (`spellCheck={false}`)
- Checkboxes and radios: label and control share one hit target (no dead zones)
- Submit stays enabled until the request starts; spinner during the request; keep the original label
- Do not pre-disable submit on incomplete forms; submitting surfaces errors
- Do not block keystrokes on typed fields; validate after input
- Enter submits when a text input is the only control; in `<textarea>`, ⌘/Ctrl+Enter submits
- Errors inline next to fields; focus the first error on submit
- Placeholders end with `…` and show an example pattern (`your_access_token_here…`)
- `autocomplete="off"` on non-auth fields to avoid password-manager triggers
- Warn before navigation with unsaved changes (`beforeunload` or a router guard)
- Auth fields belong in the shell when the app is hosted. Don't duplicate sign-in UI in the iframe unless you are replacing the identity backend

## Reuse

Prefer shipped Tailwind Plus patterns. Paste into Nunjucks or `{% demo %}`. Restyle with Shellui tokens. Native `<dialog>` / `el-dialog` on this site; shell SDK for toasts inside a hosted app.

| Job | File | Pattern |
| --- | --- | --- |
| Product opening | `src/index.njk` | Centered hero, dual CTA |
| Nav | `src/_includes/nav.njk` | Flyouts, Alpine, no new menu library |
| Feature split | `src/features/index.md`, `layouts/feature.njk` | Two-column, one dominant piece |
| Pricing | `src/pricing/index.md` | Two-tier |
| Article | `layouts/post.njk` | Narrow measure |
| Inner page | `layouts/page.njk`, `guidelines.njk` | Breadcrumb, h1, lede, prose |
| Code | `{% highlight %}` | Shiki |
| Demo | `src/blocks/*.njk` | Real HTML, no iframe |

**Shellui brand ambient** is allowed: a soft primary / amber wash (`blur-3xl`, `from-primary to-amber-200`) behind the homepage hero or a quiet CTA. Static is fine. Reject multi-color blobs, logo clouds, gradient fields, testimonial marquees, and fake dashboards. Gradients elsewhere are not allowed except this wash.

## Compose

First viewport is the argument, not a masthead plus setup. Start with the reader's job. Executive path (identity, headings, one action) and audit path (commands, config, tables) are both required. Copy follows [Writing](/guidelines/writing/).

One page-level throughline. One focal relationship per reading moment. Squint: one dominant claim. If every block has equal weight, redesign. Never fill an evidence gap with panels, icons, or effects.

Passes: frame the job → choose composition → apply Foundations tokens → inspect both themes. Deliver the implementation, not a score.

## Reject (visual)

- All-caps tracked eyebrows as decoration
- Multi-color glows, stripes, glass, ornamental shadows (soft primary/amber hero ambient is allowed)
- Generic centered hero plus equal-weight card grid
- Nested cards, or borders used to repair weak hierarchy
- Arbitrary icon tiles, logo clouds, fake screenshots
- A second theme picker, second nav, or host chrome rebuilt in an iframe
- Leading a shipping-product page with AI / MCP / marketplace atmosphere
- Authoring-process narration in page copy

Voice rejects (banned words, dashes): [Writing](/guidelines/writing/).

## Motion, touch, and layout

- Honor `prefers-reduced-motion` (reduced variant or disable). The marketing theme reveal already disables under that media query - match it
- Animate `transform` and `opacity` only (compositor-friendly)
- Never `transition: all`; list properties explicitly
- Set the correct `transform-origin`
- SVG: transforms on a `<g>` wrapper with `transform-box: fill-box; transform-origin: center`
- Animations interruptible - respond to input mid-animation
- Autoplay motion longer than 5 seconds needs pause, stop, or hide controls
- Muted decorative loops must stop under `prefers-reduced-motion`
- `touch-action: manipulation` (prevents double-tap zoom delay)
- Set `-webkit-tap-highlight-color` intentionally
- `overscroll-behavior: contain` in modals, drawers, and sheets - including shell drawers
- During drag: disable text selection, `inert` on dragged elements
- Drag, swipe, pinch, and path gestures need tap/click and keyboard alternatives unless the gesture is the whole point
- `autoFocus` sparingly - desktop only, single primary input; avoid on mobile
- Full-bleed layouts need `env(safe-area-inset-*)` for notches
- Avoid unwanted scrollbars: fix overflow rather than masking it with `overflow-x-hidden` on `body`
- Flex and grid over JavaScript measurement for layout
- Nested radii: child ≤ parent, concentric (`rounded-md` inside `rounded-xl`)
- Design empty, sparse, dense, and error states
- Inline help before tooltips
- Iframe apps: don't assume viewport height equals the window. The shell chrome eats space. Prefer `%` / flex inside the iframe, not `100vh`, unless you subtract host chrome

## Visual language

- Density: developer-facing, not crowded. Match existing `page-top`, `page-x`, `max-w-5xl` / `max-w-3xl` prose, `rounded-xl` cards, and gray borders on feature pages
- Light and dark are both first-class. Preview every screen in both. Marketing site: `html.dark` plus `localStorage.theme`. Product: `@shellui/core` theme
- `color-scheme: dark` on `html` when the dark theme is active (fixes scrollbar and native controls)
- `theme-color` meta matches the page background
- Native `<select>`: explicit `background-color` and `color` (Windows dark mode)
- Ellipsis `…`, not three dots `...`. Loading states: `Loading…`, `Saving…`
- Punctuation and banned words: [Writing guidelines](/guidelines/writing/) owns them. UI copy follows the same rules
- Straight quotes in source. Don't convert to curly quotes by hand
- `font-variant-numeric: tabular-nums` for number columns and comparisons
- `text-wrap: balance` or `text-pretty` on headings (prevents widows)
- Text containers handle long content: `truncate`, `line-clamp-*`, or `break-words`
- Flex children need `min-w-0` to allow truncation
- Handle empty states - don't render broken UI for empty strings or arrays
- User-generated content: anticipate short, average, and very long inputs
- Buttons and links need a `hover:` state. Hover, active, and focus should increase contrast, not flatten it
- Copy in the UI follows the [writing guidelines](/guidelines/writing/): active voice, sentence-case page headings, Title Case nav labels, specific button verbs ("Save token", not "Continue")
- Numerals for counts: "8 apps", not "eight"
- Error messages include the next step, not only the problem
- `&` over "and" only where space is tight (nav, buttons)
- Brand name **Shellui** never translates: `translate="no"` on the wordmark in HTML where auto-translate would garble it

## Images and themes

- Product screenshots ship as a light and dark pair with matching names: `*-light.*` and `*-dark.*`
- Open Graph images and social previews are light only. Platforms show one fixed image
- Covers and illustrations: prefer a theme-aware SVG. Otherwise use the light image in a bordered card
- In dark mode, light images sit in a subtle rounded card with a border so they don't glare
- Ship WebP with a PNG fallback. Set `width` and `height` to avoid layout shift. Lazy load below the fold
- Every image needs real `alt` text. Use `alt=""` only for decoration, and not through the shortcode

Use the `themedImage` shortcode. Pass base paths without the extension; it expects `.webp` and `.png` files with the same name. `alt`, `width`, and `height` are required, and the build fails without them. `class` and `loading` are optional; `loading` defaults to `lazy`.

```njk
{% themedImage { light: "/img/docs/files-light", dark: "/img/docs/files-dark", width: 1600, height: 1000, alt: "Files app with a shared folder open" } %}
```

For SVG, pass the full `.svg` path instead of a base path. The shortcode outputs a plain `<img>` with no WebP or PNG variants. The same required fields and `.dark` toggle apply:

```njk
{% themedImage { light: "/img/blog/cover-light.svg", dark: "/img/blog/cover-dark.svg", width: 1200, height: 630, alt: "Shellui cover" } %}
```

Leave out `dark` for a light-only image. In dark mode it renders inside a rounded card with a border:

```njk
{% themedImage { light: "/img/blog/cover", width: 1200, height: 630, alt: "Shellui cover", loading: "eager" } %}
```

## Performance and state

- `<img>` needs explicit `width` and `height` (prevents layout shift)
- Below-fold images: `loading="lazy"`
- Above-fold critical images: `fetchpriority="high"`
- Large lists (more than 50 items): virtualize or `content-visibility: auto`
- No layout reads in render (`getBoundingClientRect`, `offsetHeight`, `offsetWidth`, `scrollTop`)
- Batch DOM reads and writes; don't interleave
- Prefer uncontrolled inputs; controlled inputs must be cheap per keystroke
- Self-host third-party scripts when practical (`@shellui/sdk` tiny ships from `/assets/js/`). Use Subresource Integrity if you must load from a CDN
- Critical fonts: Inter is self-hosted with preload and `font-display: swap`. Do not add a second webfont without a reason
- Prefer compressed video over animated GIF; provide a still alternative
- Short decorative loops: muted video, `prefers-reduced-motion` media condition, still fallback
- URL reflects state - filters, tabs, pagination, expanded panels in query params. Deep-link stateful UI
- Links are real links (`<a>`), so Cmd/Ctrl+click and middle-click work
- Destructive actions need a confirmation modal or an undo window - never immediate
- Dates and times: `Intl.DateTimeFormat`, not hardcoded strings
- Numbers and currency: `Intl.NumberFormat`
- Detect language via `Accept-Language` / `navigator.languages`, not IP. The shell already owns locale
- Hydration: inputs with `value` need `onChange` (or `defaultValue` if uncontrolled)
- Date/time rendering: guard against server/client mismatch
- `suppressHydrationWarning` only where it is truly required
- Eleventy pages are static HTML. Don't hydrate a whole marketing page for a theme toggle - keep Alpine/JS scoped

## Anti-patterns (flag these)

- `user-scalable=no` or `maximum-scale=1` disabling zoom
- `onPaste` with `preventDefault`
- `transition: all`
- `outline-none` without a focus-visible replacement
- Click handler navigation without an `<a href>`
- `<div>` or `<span>` with click handlers that should be `<button>` or `<a>`
- Images without dimensions
- Large arrays `.map()` without virtualization
- Form inputs without labels
- Icon buttons without `aria-label`
- Submit disabled before the user tries (hides validation)
- Hit targets under 24px (44px on mobile) with no expanded area
- Hardcoded date/number formats (use `Intl.*`)
- `autoFocus` without a clear reason
- Animated GIF when compressed video is suitable
- Gesture-only action without tap/click and keyboard alternative
- Em dashes or en dashes as punctuation in UI copy (see Writing)
- Rebuilding shell toasts, dialogs, or nav inside the iframe
- `100vh` layouts that sit under host chrome
- A second theme picker in a hosted app
- Shipping-product UI that leads with AI, MCP, or marketplace chrome
- Missing dark-theme styles (`dark:` or theme tokens)
- Focus or headings hidden under the fixed marketing header or shell top bar

## Review output

Group by file. Use `file:line` format (clickable in VS Code). Terse findings.

    #### Example (guidelines hub)

    src/guidelines/index.njk:12 - icon button missing aria-label
    src/guidelines/index.njk:40 - heading target missing scroll-margin-top

    #### Example (CSS)

    src/assets/css/extras.css:22 - transition: all → list properties

    #### Example (pass)

    src/_includes/nav.njk - pass

State issue + location. Skip explanation unless the fix is non-obvious. No preamble.


---

# Print (v2.0.0)

https://shellui.com/guidelines/print.md

Print rules for PDFs, decks, and collateral. The downloadable [brand kit PDF](/brand-assets/shellui-brand-kit-v1.pdf) is a rendered handbook plus samples; this page is the searchable source agents and humans fetch as markdown.

## Grid and margins

- **Page size**: A4 for the brand kit
- **Margins**: 20 mm on top and sides, 22 mm on the bottom (room for the folio)
- **Grid**: 12 columns, 6 mm gutter, 2 mm baseline unit for spacing steps
- **Feature layout**: label column (3) plus content column (9), 8 mm apart

Dark pages are allowed anywhere in a document, including covers. Keep generous margins so text never touches the trim.

## Typography

- **Family**: IBM Plex Sans for every word in print (headings, body, tables, captions). IBM Plex Mono for code and numeric tables that need alignment.
- **Do not** set marketing body copy in Inter. Inter is for the website and generated screen images only.

## Page numbers

- Folio on **body pages only**, bottom right, tabular numerals
- **No page numbers on covers** or section dividers that read as covers
- Running head on body pages; covers carry title art only

## Color

- **Flat backgrounds only** in print: white, mist `#F9FAFB`, ink `#111827`, or night `#030712`
- No gradients in print, PDF export, og:image, or social images. A soft gold wash is **web only** (homepage hero ambient)
- **Brand gold** `#E3A512`: fills, rules, logo shapes. Never set body text in brand gold on white (contrast fails)
- **Text gold** `#8A6300`: gold text and links on light paper. On dark print pages, use light mist text instead of gold text
- **On gold** `#1A1408`: text on gold fills

### Pantone

| Color | Hex | Coated | Uncoated |
| --- | --- | --- | --- |
| Brand gold | `#E3A512` | 124 C | 7405 U |
| Text gold | `#8A6300` | 4027 C | verify against swatch |

Always verify coated and uncoated references against a **physical Pantone swatch** before the first production run. Digital hex is the day-to-day source; Pantone is the print handshake.

## Paper

Suggested stocks for brand kit reprints and one-pagers:

- **Coated**: 150 gsm silk or equivalent for full-color pages with photography
- **Uncoated**: 120 gsm offset for mostly type and line art
- **Covers**: 250 gsm when the piece will be handled often

Ask your print vendor to match `#E3A512` and `#8A6300` with ink drawdowns, not only a Pantone name from a PDF.

## Logo in print

Logo usage, clear space, and misuse pairs live in [Brand](/guidelines/brand/). Use official files from [Downloads](/guidelines/brand/#downloads). No lockups in v1: wordmark and mark stay separate.

## How to use this file

- **Humans**: `/guidelines/print/`
- **Agents**: fetch `https://shellui.com/guidelines/print.md`
- **Hub**: [Guidelines](/guidelines/)


---

# Guidelines changelog (v2.0.0)

https://shellui.com/guidelines/changelog.md

## 2.0.0 (2026-10-25)

Major reorganization for the website release.

- **Hub**: overview plus cards for Brand, Foundations, Writing, Interface, Print, and this changelog
- **Brand**: identity and [Downloads](/guidelines/brand/#downloads) replace the standalone brand assets page (URLs redirect)
- **Foundations**: token source `tokens/tokens.json` generates CSS, tables, and downloads
- **Interface**: merges former design and web design guidelines; `/design.md` stays as agent alias
- **Print**: new HTML and markdown for print grid, IBM Plex, folios, Pantone, and paper
- **Writing**: sole owner of punctuation and banned words
- **Agents**: `llms-full.txt`, raw `.md` twins; `/design.md` trimmed alias; `/guidelines/web-design.md` full Interface copy
- **Site**: Inter self-hosted on screen; text gold `#8A6300` / `#E8B84A` in dark mode

## 1.x (archived)

Prior versions lived as separate writing (1.0.0), web design (1.1.1), design (1.3.1), and brand (1.0.0) files. Legacy HTML pages at `/guidelines/design/` and `/guidelines/web-design/` fall back to Interface.