Kuickr House Style

The canonical guide for authoring rich pages that Kuickr hosts. Read this before you write a page, whether you are a human, the CLI, or an agent using the MCP kuickr_style_guide tool.

Building something rich, animated, or design-forward? First call kuickr_recipes (action=search — e.g. "animated landing", "gradient hero", "3d mockup", "scroll story") for a proven recipe with copy-paste technique, then apply this house style over it.

Kuickr pages should feel like permanent, useful documents: structured, scannable, token-driven, and easy to revisit. The current design authority is the design-system registry, not a copied private palette.

Design systems

Agents and humans choose a named design system before authoring.

Fetch the current registry instead of copying stale tokens:

GET /api/v1/design-systems
GET /api/v1/design-systems/kuickr-v2/tokens.css
GET /api/v1/design-systems/kuickr-v2/DESIGN.md
GET /api/v1/design-systems/kuickr/tokens.css
GET /api/v1/design-systems/kuickr/DESIGN.md
GET /api/v1/design-systems/game/tokens.css
GET /api/v1/design-systems/game/DESIGN.md
GET /api/v1/design-systems/inventlist.com/tokens.css
GET /api/v1/design-systems/nodepad/tokens.css

Over MCP:

kuickr_list_design_systems
kuickr_get_design_system { "id": "kuickr-v2" }
kuickr_get_design_system { "id": "kuickr-v2", "version": "20db7cd5-eaee-42a7-a52a-a81fba8250e2" }
kuickr_get_design_system { "id": "kuickr" }
kuickr_get_design_system { "id": "game" }
kuickr_get_design_system { "id": "inventlist.com" }
kuickr_get_design_system { "id": "nodepad" }

The registry default is kuickr-v2. Its Winter light palette uses ink #12181F, frost #EEF2F5, and ice #2F7FB0; its dark palette uses a Blue-charcoal #121B24 canvas, #1D2A35 cards, and #5AAFE2 ice. Libre Baskerville is display, Space Grotesk is UI/body, and JetBrains Mono is for code/meta. Kuickr-owned chrome may follow the operating-system dark preference when no theme is set, while an explicit data-theme="light|dark" always wins. Authored portable pages should ship both explicit theme states so their result is deterministic wherever it is embedded.

Ice is an orientation semantic: links, focus rings, active navigation, selection, and non-text indicators. Do not use ice for small body text or as a filled control behind text; use the readable ink/text roles and reserve semantic red, violet, amber, and teal-green for meaning. kuickr keeps the retained v1 brass system for exact compatibility reads, but it is no longer the default.

The game system uses NOCTURNE --gm-* tokens: midnight ink, cream text, ember-to-gold living light, ice-teal live state, beveled instrument panels, and the same display/UI/mono font trio as Kuickr. Use it only for the play shell, MCP-authored games, and published game pages. It is intentionally separate from docs and books.

The Nodepad system uses the app/product track from the InventList docs: Inter for body UI, Instrument Serif for display headings, and JetBrains Mono for metadata, refs, timestamps, and keyboard hints. Runtime-book/editorial mockups may use Fraunces, but hosted Nodepad-style pages should start with the product track. Font size settings are S 13px, M 15px, L 17px; the default is M 15px. Composer scale is title 22px, body 15px, metadata 11px. Reading widths are narrow 576px and wide 768px. Rhythm is 4/8/12/16/24/32/48/72px.

Token Rules

1. Use one named design system per page unless the page is explicitly comparing systems.
2. Inline or link the fetched token CSS before page styles.
3. Reference tokens with var(--kk-...), var(--gm-...), var(--np-...), var(--kind-...), or var(--operator-...).
4. Do not hard-code product colors in page CSS. Raw hex values belong in token files only.
5. Use explicit theme attributes: light by default, [data-theme="dark"] only when a page ships a real dark variant.
6. Scope the selected Page-body system to a dedicated wrapper. Kuickr v2 belongs on the chrome root; never load v1 and v2 as competing global :root declarations.
7. Keep generated HTML self-contained when it is sandboxed; do not assume the Kuickr chrome CSS will leak into the iframe. Sandboxed HTML stays isolated in its iframe.

Page Anatomy

Use this structure for rich docs and high-bearing pages:

1. Eyebrow: mono, uppercase context such as Spec 35 / design system.
2. Title: one clear h1; use the design-system display font.
3. Lede: one or two sentences that explain the outcome.
4. Meta row: owner/source/status/revision/date.
5. Sections: short h2 headings, each with a one-line setup when useful.
6. Structured blocks: tables, callouts, code blocks, flow rows, and status rows.
7. Footer: source path, revision, and Kuickr attribution when relevant.

Minimal Kuickr HTML skeleton:

<div class="page" data-theme="light">
  <style>
    /* Paste the tokens_css returned by kuickr_get_design_system here. */
    body {
      margin: 0;
      background: var(--kk-wash);
      color: var(--kk-text);
      font-family: var(--kk-font-ui);
      line-height: 1.6;
    }
    .page {
      max-width: var(--kk-read);
      margin: 0 auto;
      padding: var(--kk-s-7) var(--kk-s-5);
    }
    .eyebrow {
      font-family: var(--kk-font-mono);
      font-size: 11px;
      letter-spacing: .12em;
      text-transform: uppercase;
      color: var(--kk-secondary);
    }
    h1 {
      font-family: var(--kk-font-display);
      font-weight: 400;
      font-size: 48px;
      line-height: 1.08;
      color: var(--kk-ink);
    }
    .callout {
      border-left: 3px solid var(--kk-secondary);
      background: var(--kk-secondary-soft);
      border-radius: var(--kk-r-sm);
      padding: var(--kk-s-4);
    }
  </style>

  <div class="eyebrow">Spec 35 / design system</div>
  <h1>Project Atlas</h1>
  <p class="lede">One sentence on what this is and who it is for.</p>
  <p class="meta">status: partial / rev 1 / 2026-06-29</p>

  <h2>At a glance</h2>
  <table>
    <tr><th>Thing</th><th>State</th></tr>
    <tr><td>Token system</td><td>current</td></tr>
    <tr><td>MCP delivery</td><td>available</td></tr>
  </table>
</div>

Minimal Nodepad HTML skeleton:

<div class="np-tokens np-wash page" data-theme="light" data-density="comfortable" data-font-size="m">
  <style>
    /* Paste the tokens_css returned by kuickr_get_design_system {"id":"nodepad"} here. */
    body {
      margin: 0;
      background: var(--np-wash);
      color: var(--np-text);
      font-family: var(--np-sans);
      font-size: var(--np-font-size);
      line-height: var(--np-line-height-body);
    }
    .page {
      max-width: var(--np-reading-narrow);
      margin: 0 auto;
      padding: var(--r-6) var(--r-4);
    }
    h1 {
      font-family: var(--np-display);
      font-size: var(--np-font-size-title);
      line-height: var(--np-line-height-title);
      color: var(--np-ink-runtime);
    }
    .meta {
      font-family: var(--np-mono);
      font-size: var(--np-font-size-meta);
      color: var(--np-muted);
    }
    .kind {
      font: 600 var(--np-font-size-kind)/1 var(--np-sans);
      letter-spacing: .04em;
    }
    [data-theme="dark"] .page {
      background: var(--np-wash);
      color: var(--np-text);
    }
  </style>

  <p class="meta">nodepad / light default / dark ready</p>
  <h1>Working notes</h1>
  <p>Use Nodepad tokens for app/workspace pages, capture docs, and notepad-style surfaces.</p>
</div>

Mobile & responsive

Kuickr is used on phones as much as laptops — family games, shared reader links, quick edits. Design mobile-first: build the smallest screen first, then add room. Non-negotiables:

1. No horizontal page scroll, ever. The body never scrolls sideways. Wide content (tables, code, diagrams, a game canvas) gets its own overflow-x: auto container; everything else wraps.
2. Everything works from ~320px up. Test at 320 / 375 / 414 CSS px, portrait and landscape.
3. Breakpoints, few and shared: phone ≤ 560px, tablet ≤ 860px, desktop above. Don't invent per-component widths — reuse these.
4. Touch targets ≥ 44×44px on any interactive control (buttons, icon buttons, toggles, links in a bar). Give them enough spacing that a thumb can't mis-tap a neighbour.
5. Respect safe areas. Anything anchored to a screen edge — bottom bars, FABs, sticky headers — pads with env(safe-area-inset-*) so it clears notches and the iOS home indicator.
6. Control bars become a bottom sheet, not a crammed strip. A horizontal toolbar that fits on a laptop must, on a phone, collapse to a FAB or wrap into a stacked, full-width sheet. Never let a row of controls overflow off-screen.
7. Fluid type and space. Size heroes/headings with clamp(); lay out with flex/grid + gap and relative units, not fixed pixel widths that overflow. Images/media get max-width: 100%.
8. Keep the reading measure (~65ch / var(--kk-read)) on text, and let it reflow — don't pin column widths that force a zoom-out on mobile.

These apply to every surface — deck app, reader, games, marketing, and agent-authored pages alike.

Reader bar (full view) — declare how it sits on your page

When your page is opened in full view (?view=full), Kuickr floats a reader bar (brand · search · pager · comments · like) over it. You choose how that bar sits by putting one attribute on your page's root element:

<div data-kuickr-bar="dock">   <!-- dock | float | peek -->

• dock (default) — a full-width bar; the page is inset so nothing hides under it. Best for pages with their own bottom-anchored UI (an order dock, a game HUD).
• float — a compact pill hovering bottom-centre. Best for long reading where you want the page edge-to-edge.
• peek — the bar folds to a small corner button; tap to expand. Most immersive.

Omit the attribute and the Page uses its saved Page default, then its Folder default, then dock. Owners can set Page and Folder defaults from the Page settings sheet; an explicit Page setting wins over this authored attribute. A reader can still switch modes with the bar chevron, and their private browser choice is remembered above every author/owner default. MCP/CLI authors can keep using the attribute without a separate tool. Kuickr reads it server-side from the page source because the sandboxed iframe is cross-origin. On phones, every mode resolves to the docked bottom bar; these defaults and the reader chevron apply to desktop placement.

Hosting a file, not just a page (PDF · spreadsheet · image)

Kuickr hosts binary files too, not only HTML/markdown — don't wrap a file in an HTML page. Upload the raw bytes with kuickr_page using encoding: "base64" and the real filename:

kuickr_page { action: "create", org, folder, path: "menu.xlsx",
              encoding: "base64", content: "<base64 of the .xlsx>" }

Kuickr classifies it by extension (Marcel MIME) and renders it in its own chrome:

• .xlsx / .xls → a spreadsheet page — tabbed HTML tables (server-parsed, private-safe; read-only: computed values, not formulas/charts).
• .pdf → an in-page PDF viewer. images → shown inline. Other types → a download card.

Wrapping a file inside an HTML page is worse: you lose the native chrome and the embedded bytes still count against the size cap. Cap: one kuickr_page call is 256 KB of content (base64 inflates ~33%, so ~190 KB of raw file); append can't grow a binary. Larger files aren't uploadable over MCP yet.

Placing an intake form inline

A page with an enabled intake (order / form / meeting) shows its form auto-appended at the bottom by default. To put it exactly where you want in a markdown page, drop a macro on its own line:

## Menu

Lentil Dahl — $12 · Chicken Biryani — $15

{{intake:order}}

Delivered fresh. Halal.

• Kinds: {{intake:order}} · {{intake:form}} · {{intake:meeting}} — on their own line.
• The form renders only if that intake is enabled on the folder (kuickr_folder action=intake); an unknown or disabled kind's macro is stripped (never shown raw).
• Placing a macro turns off auto-append for that kind — so no duplicate at the bottom. Other enabled kinds you didn't place still auto-append.
• Markdown only (a sandboxed HTML page can't host the parent-rendered panel; use the page's own UI there).

Writing Rules

1. Lead with the outcome. The first screen should answer what this is and why it matters.
2. Keep prose to a reading measure around var(--kk-read) or the selected system's equivalent.
3. Use tables for structured facts; do not bury state in paragraphs.
4. Use callouts for constraints, decisions, blockers, and risks.
5. Tag code fences with a language.
6. Link relatively inside a hosted folder when possible (other.html, sub/x.html, ../y.md).
7. Use the canonical URL returned by kuickr_pages for exact page references.
8. Keep one visual family per page. Mixing --kk-* and --np-* is only for comparison pages.
9. Match sibling pages before editing: search/read them first, then write.
10. Prefer durable headings and clear section names over decorative copy.

Authoring Via MCP

Use this sequence:

1. Call kuickr_style_guide.
2. Call kuickr_list_design_systems.
3. Call kuickr_get_design_system for the intended system and paste or apply its tokens_css. For the default system, read /api/v1/design-systems/kuickr-v2/DESIGN.md when you need the design rationale and component guidance, not just raw CSS.
4. Use kuickr_pages with action=search or action=read to match nearby pages.
5. Use kuickr_page with action=create or action=append to publish.

For the requested Nodepad app/workspace look, choose nodepad; for broader InventList.com docs, choose inventlist.com; for Kuickr's own product look, choose kuickr-v2; choose kuickr only for deliberate legacy-v1 compatibility. To reproduce an exact retained result, pass the listed opaque UUID as version to kuickr_get_design_system.

See also: Design systems ↗ — the token sets a page can be authored in.