Amili Interface Guidelines

Principles

Five ideas behind every decision below. When two rules seem to clash, the principle decides.

1. p-1Calm

   The interface serves the content. One accent colour, quiet surfaces, motion only as feedback. Nothing blinks, autoplays or covers what someone is reading.

2. p-2One voice, an honest one

   Every surface looks and sounds like the same product: the same tokens, the same mark, the same word for the same action. No dark patterns: saying no is as easy as saying yes, nothing is pre-ticked, prices and affiliate links are labelled, and nothing is called live before it ships.

3. p-3One clear next step

   Each screen says what it is for, puts the answer first and ends with one next step for the reader. One primary button per view; everything else is quieter.

4. p-4Fast and solid

   Rendered on the server, no framework, no font download, no layout shift. The default state is already in the HTML; scripts only add to it.

5. p-5For everyone

   Targets of at least 44px, a visible focus ring, real labels, contrast checked against WCAG 2.2 AA in every theme, usable at 200% zoom and with reduced motion.

Colour

Colours are roles, not values. A page names the role (page, card, text, action) and the Kit decides the value for light, dark and Warm night.

1. col-1Use the short role names in page CSS: --bg, --panel, --panel2, --line, --txt, --dim, --accent, --on-acc, --acc-soft, --err, --input-bg. Never write a colour value in a page; the build refuses a page-local colour token.
2. col-2The accent means "you can act here" or "you are here": the primary button, links, the current tab, the selected card. Do not use it for decoration or to emphasise plain text.
3. col-3Text and icons on an accent fill use --on-acc. Never put --dim or --txt on --accent.
4. col-4--err is for errors only, and always comes with words that say what is wrong. Colour alone never carries meaning.
5. col-5Show state by shade, not by loud blocks: selected is an --acc-soft fill with an accent edge; hover is a small opacity or border change.
6. col-6Surfaces step: --bg for the page, --panel for cards, menus and fields, --panel2 for a band or a quiet fill, --line (1px) to separate. Cards carry no shadow at rest; only things that float (a menu, a sheet) get --shadow.
7. col-7Check every colour pair in light, dark and Warm night, and with each accent from the picker.
8. col-8Amili's own pages use the evergreen accent. Blue, graphite, amber and Warm night are the user's choice in the app, never the default of a page.

Typography

Two families with clear jobs and a short scale. The serif speaks; the sans works.

1. typ-1--serif is for headings, the wordmark and Amili's own voice (an answer, a quote). --sans is for everything people read to operate the page: body, labels, buttons, menus, tables.
2. typ-2Use the scale: --t-xs for meta only (never body), --t-sm for captions and kickers, --t-md for secondary text and menus, --t-lg for body, --t-xl for a lead or a card title. Display headings above that use clamp() at page level.
3. typ-3Body is --t-lg at line-height 1.6. Text in a form field is at least 16px so phones do not zoom in.
4. typ-4Two weights: 400 and 600. Serif headings at 400, buttons and labels in the sans at 600. No light or thin weights.
5. typ-5Sentence case everywhere. Uppercase only for a short kicker in --t-sm with letter-spacing .08em.
6. typ-6Keep running text between 34 and 44em wide; balance headings with text-wrap:balance.
7. typ-7System fonts only (the --serif and --sans stacks). No web-font download on Amili sites.

Layout and spacing

Designed at 390px first, then widened. Space does most of the grouping.

1. lay-1Design at 390px first. There is never horizontal scroll at 390px; wide tables and chip rows scroll inside their own box.
2. lay-2Spacing comes from --s-1 to --s-6 (4px, 8px, 12px, 16px, 24px, 32px). Gaps between page sections are multiples of 8 (48, 56, 72).
3. lay-3The side gutter is --s-4 (16px) and respects the safe area: padding-left:max(16px, env(safe-area-inset-left)), the same on the right.
4. lay-4Widths: running text 34 to 44em, page content up to 1080px, header and footer up to 1240px.
5. lay-5Most important first: the intro says in one sentence what the page is for; the answer comes before the detail.
6. lay-6Group with space and hairlines first. Use a card only for a unit people act on or compare (a plan, a product, a contact).
7. lay-7Break by content, not by device: one column on phones, two from about 760px, a side table of contents from about 960px, the full menu from 48rem.
8. lay-8Anything fixed to the bottom (a consent bar, a buy bar) adds env(safe-area-inset-bottom) and pads the page so it never hides the end of it.

Shape

A small set of corner radii, each with one job.

1. shp-1Every border-radius is a --r-* token or 0. The design lint refuses anything else.
2. shp-2Buttons, text fields and chips are pills (--r-pill). Cards use --r-card; menus, popovers and inner panels --r-md; tabs --r-tab; small controls in dense parts --r-sm; the focus ring and tiny tags --r-xs.
3. shp-3Nested corners get smaller inside: an inner panel in a card uses --r-md, not --r-card.
4. shp-4A card is --panel, a 1px --line border, --r-card corners and --s-5 padding. No shadow at rest.
5. shp-5Keep a control group consistent: do not mix pill and square corners in one row of buttons.

Motion

Motion confirms that something happened. It is short, it never moves the layout, and it disappears when people ask for less.

1. mot-1Animate state, not decoration: colour and opacity changes over --dur-fast (hover, press) or --dur (open, copied) with --ease.
2. mot-2Never animate size or position of controls. Buttons never grow; a text field may get taller, the buttons next to it stay 44px.
3. mot-3Under prefers-reduced-motion: reduce, changes happen at once. Smooth scrolling only under no-preference.
4. mot-4Nothing autoplays. Video plays on tap. Nothing flashes more than three times a second.
5. mot-5The mark's asterisk may breathe by opacity only; it stops under reduced motion.
6. mot-6Do not animate transform on text or the logo: it blurs on some screens.

Accessibility

Built in from the first line, then checked. We say "checked against WCAG 2.2 AA", never "compliant": an automated check finds part of the problems, not all.

1. a11y-1Every target is at least 44 by 44px. Primary buttons are 52px tall; booking and buy buttons may be 56px. Inline links in running text get a 44px tap area with padding, without moving the lines.
2. a11y-2Contrast: at least 4.5:1 for text, 3:1 for large text and for the edges of controls, in every theme and accent.
3. a11y-3Focus is always visible: :focus-visible gets outline:2px solid var(--accent), outline-offset:2px, radius --r-xs. Never remove an outline without a replacement.
4. a11y-4Every control has a visible label or an aria-label. A placeholder is never the label. An icon inside a labelled control is aria-hidden.
5. a11y-5Status and results are announced: put them in an element with role="status" or aria-live="polite". An error names the field and the fix, and focus moves to it.
6. a11y-6Structure: html lang set, header, nav with aria-label, main, footer; one h1; headings in order; the current page marked with aria-current="page".
7. a11y-7The page works at 200% zoom and with larger text: nothing is clipped and nothing needs horizontal scroll.
8. a11y-8Check with axe-core at 390 and 1280px in light and dark, plus a keyboard pass. Fix every critical and serious issue before launch, and say "checked against WCAG 2.2 AA".

Writing

Plain words, said once, in the voice of someone who is helping.

1. wri-1Plain words, active voice, short sentences. Read it aloud; cut every word that does not change the meaning.
2. wri-2Buttons start with a verb and say what will happen: "Request a site", "Save choice", "Copy". Not "Submit", "OK" or "Let's go!".
3. wri-3End a page or an answer with one next step for the reader, said to them: "For you: …" (Dutch: "Voor jou: …").
4. wri-4No hype, no superlatives, no invented numbers. A number is measured and dated, or it is left out.
5. wri-5What is not built yet is tagged "Coming". Never claim an integration, a result or a price before it exists.
6. wri-6An error says what happened, whose side it is on and what to do: "That didn't save. The problem is on our side. Try again in a moment?"
7. wri-7One language per page, never mixed. English is the base; Dutch uses je and jij.
8. wri-8The same word for the same thing everywhere: Say, Do and Know; Decline and Allow; Request a site.
9. wri-9Sentence case for headings, buttons and menu items. No emoji as icons or bullets.

Icons

Simple line icons that sit next to words, drawn the same way everywhere.

1. ico-1Inline SVG on a 24 by 24 grid: fill none, stroke currentColor, stroke-width var(--stroke) (1.75 as an SVG attribute, where CSS variables do not work), round caps and joins.
2. ico-2Sizes: 18px inside text and table cells, 22px in lists, 26px on cards and in the side rail. Match the weight of the text next to it.
3. ico-3An icon next to words is aria-hidden="true". An icon-only button has an aria-label and a 44px target.
4. ico-4No emoji as icons, no icon fonts, no third-party logos as decoration.
5. ico-5One style per page: do not mix filled and outlined icons.

Dark mode and Warm night

Websites follow the system setting. The app adds a choice: Light, Dark, Warm night and an accent.

1. drk-1Pages follow prefers-color-scheme. Websites get no theme toggle of their own; the app's settings offer Light, Dark, Warm night and the accent (data-theme and data-acc on html).
2. drk-2Dark is not inverted light. Surfaces get lighter as they come forward (--bg, then --panel, --panel2, --elev); the accent gets lighter and text on it turns dark.
3. drk-3Every page sets color-scheme:light dark and the two theme-color metas (light and dark page colour) from the Kit.
4. drk-4Images and screenshots work on both: supply a dark version or choose one without a white box around it.
5. drk-5Warm night is a dark theme with warm ink and an amber accent; the accent picker does not apply under it.

Navigation

People should always know where they are and get back in one move.

1. nav-1A short, fixed menu (four to five items), a language switch and one call to action. The current page has aria-current="page" and an accent underline, in normal weight so the row does not jump.
2. nav-2On phones the header is one row: the mark, the language, a Menu button that opens a panel, and the one call to action.
3. nav-3A header that slides away while reading down comes back as soon as the reader scrolls up a little. It carries no background block, shadow or blur of its own and never covers content; jump targets use scroll-margin-top.
4. nav-4Pages deeper than one level show breadcrumbs (Kit breadcrumbs, with BreadcrumbList data).
5. nav-5Long pages get a table of contents: a sticky list beside the text on desktop, a row of chips that scrolls sideways on phones, and the current section marked.
6. nav-6Search lives in one place. On phones it opens as a full-screen sheet with a 44px field and a 44px close button.
7. nav-7Use a dialog or sheet only for a short task that needs a decision. It has an obvious close, Escape closes it, and it never opens another dialog on top.

Forms and entering data

Ask for little, explain it clearly, and never lose what someone typed.

1. frm-1The label sits above the field and stays visible. Help text goes under the label. A placeholder is only an example.
2. frm-2Fields are pills, at least 52px tall, 16px text, background var(--input-bg), a 1px --line border and an accent focus outline.
3. frm-3Ask only what is needed now. Use the right type, inputmode and autocomplete; offer a choice instead of typing when the answers are known.
4. frm-4Check on submit or when leaving a field, not on every key. Keep what was typed, put the message next to the field and move focus there.
5. frm-5The submit button says what happens and reads "One moment…" while sending. It is disabled only while sending.
6. frm-6Say "done" only after the server confirmed it. If it failed, say so and keep the form filled.
7. frm-7A text area grows with its text; the buttons next to it keep their size.

Feedback

Every action gets an answer, in place and sized to the action.

1. fbk-1Confirm in place: the button that copied says "Copied ✓", the field that saved says "Saved". No toast for a small thing, no alert for something that is not critical.
2. fbk-2"Was this page helpful?" offers Yes and No, the same size and weight. After a choice, an optional text field ("What would have helped?") with Send and Skip. Thank once and do not ask again on that page.
3. fbk-3Ask for confirmation only before something that cannot be undone, and say exactly what will be lost.
4. fbk-4When something cannot be done, say why and what the person can do instead.

Loading and empty states

Something useful is on screen at once, and nothing jumps when the rest arrives.

1. lod-1Render the default state on the server: a calculator shows its default result, a list shows its first items. Scripts add to the page; they do not build it.
2. lod-2Reserve space for what arrives later: width and height on images, a min-height on result areas. No layout shift.
3. lod-3A wait of more than about a second says so in words ("One moment…"); a long one says what is happening.
4. lod-4An empty state says what is missing and offers the one next step. Never an empty box.
5. lod-5Keep the rest of the page usable while something loads.

Consent

The Kit consent bar: one sentence, two equal buttons, nothing loads before a yes.

1. cns-1Nothing that measures or tracks loads before Allow. Use the Kit consent bar (Consent Mode defaults to denied where the law asks).
2. cns-2Decline comes first. Decline and Allow have the same size, style and weight. Nothing is pre-selected or focused when the bar appears.
3. cns-3One plain sentence that names the tools (Google Analytics, Microsoft Clarity) and links to the privacy page.
4. cns-4A "Cookie settings" button in the footer reopens the bar. The choice is kept for 12 months; Escape means Decline.
5. cns-5While open, the bar pads the page so it never hides the end of it.

Buying and affiliate links

A buy button is labelled as one, kept apart from advice, and never pushes.

1. buy-1An affiliate link says so next to the button ("Affiliate link") and in the footer, and carries rel="sponsored nofollow noopener".
2. buy-2Never place a paid or affiliate link inside an editorial list or ranking.
3. buy-3A price is live or absent. Never a stale or invented price.
4. buy-4The sticky buy bar (Kit buybar) sits in the flow, is 56px tall with a 44px button, respects the safe area, and appears once per page.
5. buy-5No fake scarcity, countdowns or confirmshaming ("No, I don't like saving money").

Onboarding and choosing a plan

Let people see what they get, side by side, and choose without pressure.

1. pln-1Plan choice uses the Kit plan-compare: the same labelled rows, in the same order, in every card.
2. pln-2Mark at most one advised plan with a ribbon. The visitor chooses; no add-on is pre-ticked.
3. pln-3Each price shows the currency, the period and whether VAT is included. A struck-through old price only for a real discount.
4. pln-4Minimum term and how to cancel are visible before paying. Cancelling is as easy as signing up. A trial that turns paid is announced 3 days before.
5. pln-5Let people try before asking for setup; ask for a permission or a detail only when the feature needs it; every onboarding step can be skipped.
6. pln-6Rows past the fold hide behind "Show all" but stay in the HTML.

Components

Every module in the Kit (kit/*.mjs, listed from the folder itself), what it is for, what it exports and where to see it. Use a Kit module before writing your own.

• Brand tokens and markbrand-amili.mjs

  Colour roles (light, dark, Warm night, accent picker), type, radius, spacing, motion, the wordmark and the icon. Every page includes it first.

  TOKEN_CSS, TOKEN_SOURCE, BRAND_CSS, MARK_HTML, ICON_SVG, THEME_COLOR, BRAND_JS

  This page

• Footerfooter.mjs

  The site footer: purpose line, links, business details, legal links, language switch, Cookie settings.

  AMAZON_TM, validateFooterConfig, creditHref, CLIENT_CREDIT_URL, clientCreditHref, renderFooter, FOOTER_CSS, CLIENT_CREDIT_CSS

  Demo in the Kit

• Consent barconsent.mjs

  Cookie choice before any measuring tag; Decline and Allow equal.

  EEA_UK_CH_CA, ASK_ZONES, KEEP_MS, STRINGS, langOf, settingsLabel, consentHead, renderConsent, CONSENT_CSS, CONSENT_JS

  Demo in the Kit

• Amili Searchsearch.mjs

  Site search over a prebuilt index; full-screen sheet on phones.

  engine, brandMark, renderSearch, BRAND_CSS, SEARCH_CSS, LAUNCHER_CSS, searchScript, SEARCH_JS

  Demo in the Kit

• Search index buildersearch-build-index.mjs

  Build step: writes the search index from the built pages.

  pageRow, buildIndex

  Demo in the Kit

• Search injectorsearch-inject.mjs

  Build step: adds search to every built page.

  strip, injectHtml, run

  Demo in the Kit

• Table of contentstoc.mjs

  Jump list on long pages, chips on phones, current section marked.

  slugify, shortLabel, brandMark, collectHeadings, renderToc, addToc, BRAND_CSS, TOC_CSS, TOC_JS

  Demo in the Kit

• Breadcrumbsbreadcrumbs.mjs

  Where you are on deep pages, with BreadcrumbList data.

  jsonForScript, validateBreadcrumbs, breadcrumbJsonLd, renderBreadcrumbs, BREADCRUMBS_CSS

  Demo in the Kit

• FAQfaq.mjs

  Questions and answers that fold, with FAQPage data.

  jsonForScript, brandMark, validateFaq, faqJsonLd, renderFaq, BRAND_CSS, FAQ_CSS

  Demo in the Kit

• Related linksrelated.mjs

  "Keep reading": one lead link and a few smaller ones, rendered on the server.

  brandMark, pickRelated, renderRelated, BRAND_CSS, RELATED_CSS

  Demo in the Kit

• Comparison tablecompare.mjs

  Products or plans in a table with a sticky header and pinned first column.

  validateCompare, bestCells, renderCompare, COMPARE_CSS, COMPARE_JS

  Demo in the Kit

• Calculator shellcalculator.mjs

  Labelled inputs and an announced result, default result already in the HTML.

  brandMark, formatNumber, validateCalculator, renderCalculator, BRAND_CSS, CALC_CSS, CALC_JS

  Demo in the Kit

• Sticky buy barbuybar.mjs

  One labelled buy action that stays in reach on long product pages.

  validateBuyBar, renderBuyBar, BUYBAR_CSS, BUYBAR_JS

  Demo in the Kit

• Amazon product cardamazon-ad.mjs

  Product image, live price and a clear, labelled affiliate button.

  VARIANTS, CACHE_TTL_S, MAX_AGE_MS, DISCLAIMER, hash32, utcDay, candidatesFor, pickProducts, validatePool, parseItem, API_RESOURCES, makeItemsHandler, makeGateHandler, validateAdConfig, renderAd, renderAdSlots, AD_HEAD_JS, RANK_JS, AD_JS, AD_CSS

  Demo in the Kit

• Click beaconbeacon.mjs

  Cookie-free click counts per position, for choosing placements.

  beaconScript, makeBeaconHandler, kvCounter

  Demo in the Kit

• Plan choiceplan-compare.mjs

  The choose-a-plan step of onboarding: cards with the same rows, one advised.

  renderPlanCompare, PLAN_COMPARE_CSS, PLAN_COMPARE_JS

  This page

• Copy blockcopy-block.mjs

  A ready-to-paste text with one copy button that confirms in place.

  renderCopyBlock, COPY_BLOCK_CSS, COPY_BLOCK_JS

  This page

• Heading foldheading-fold.mjs

  A section that folds behind its heading, with a count of what is inside.

  renderHeadingFold, HEADING_FOLD_CSS, HEADING_FOLD_JS

  No demo yet

• Contact cardcontact-card.mjs

  An organisation as a card with big call, mail and open buttons.

  HALF_MAX, renderContactCard, renderContactCards, CONTACT_CARD_CSS, CONTACT_CARD_JS

  No demo yet

• Page from Markdownpage-md.mjs

  Markdown with Kit blocks (folds, copy blocks, contact cards, checklists, tables) as one page; used by amili.ai/p/.

  keyOf, inline, renderPageMarkdown, PAGE_MD_CSS, PAGE_MD_JS, PAGE_MD_ALL_CSS, PAGE_MD_ALL_JS

  No demo yet

• Side railside-rail.mjs

  Sticky actions at the right edge (request, prices, examples, WhatsApp); steps aside over text.

  ICONS, renderSideRail, SIDE_RAIL_CSS, SIDE_RAIL_JS

  Live on every indexable amili.ai page

• Session barsession-bar.mjs

  "Signed in as …" and a real Log out, for pages behind a sign-in.

  renderSessionBar, SESSION_BAR_CSS

  No demo yet

• Showcaseshowcase.mjs

  The agency layout of amili.ai: display hero, device frames, work grid, plan columns.

  pic, browser, phone, sitePreview, sitePreviews, eyebrow, offerBadge, factChips, vsRow, SHOWCASE_CSS, SHOWCASE_JS

  amili.ai home

• Say decksay-deck.mjs

  The app's Say view: one message at a time, Amili's answer in the serif, and the composer.

  ICON, sayIcon, sayDeckModel, SAY_DECK_CSS, sayDeckHtml, sayNavHtml, sayToolsHtml

  No demo yet

Gaps: what the Kit does not have yet

• Buttons and text fields: no Kit module yet. Pages write them from tokens (pill, 52px, --accent / --input-bg), as shown on this page.
• Header and menu: amili.ai's header is written by scripts/chrome.mjs, not a Kit module, and it does not yet slide away and come back on scroll-up (nav-3); the fleet header does.
• "Was this page helpful?": no Kit module and no endpoint yet. The demo on this page sends nothing.
• Dialog or sheet, status message (toast), tabs or segmented control, switch and checkbox: no Kit module yet.
• Empty state and loading placeholder: no Kit module yet (pattern only).
• Display heading sizes are clamp() values per page, not tokens; a --t-display token is still to come.
• No Dutch edition of these guidelines yet.

Theming for brands

A brand built with the Kit changes its colour, type families and corners by overriding --ak-* values after the Kit CSS. The rest is the system and stays.

A brand may change

1. thm-1The accent family, in light and dark: --ak-acc, --ak-soft, --ak-on (text on the accent), --ak-mine, --ak-wash. Text on the accent must reach 4.5:1 and the accent on the page 3:1.
2. thm-2The surfaces --ak-s0 to --ak-s3 and --ak-line, if text keeps 4.5:1 on every one of them, in light and dark.
3. thm-3The two font families --serif and --sans (system stacks or one self-hosted family; no layout-shifting web-font swap).
4. thm-4Corner radii as a set: --r-card, --r-md and --r-sm may become squarer or rounder together. --r-pill stays a pill for buttons and fields.
5. thm-5The mark: a brand uses its own logo in place of the Amili mark.

Stays the same

1. thm-6The spacing scale --s-1 to --s-6 and the type scale --t-xs to --t-xl.
2. thm-7The role names (--bg, --panel, --txt, --accent …): override the --ak-* values, never rename or bypass the roles.
3. thm-844px targets, the focus ring rule, the contrast minimums and reduced motion.
4. thm-9--stroke (1.75), --dur-fast (.15s), --dur (.2s) and --ease (ease-in-out).
5. thm-10The honest patterns: consent, affiliate labels, plan choice and "Coming" tags.

Example override

/* Brand override: put it AFTER the Kit's brand CSS. Example values for an imaginary bakery. */
:root{
  --ak-acc:#8A3B12; --ak-soft:rgba(138,59,18,.11); --ak-on:#FFFFFF; --ak-mine:#8A3B12; --ak-wash:#C46A3A;
  --serif:"Iowan Old Style",Charter,Georgia,serif;
  --r-card:12px; --r-md:10px; --r-sm:8px;
}
@media (prefers-color-scheme:dark){:root:where(:not([data-theme=light])){
  --ak-acc:#F0A57A; --ak-soft:rgba(240,165,122,.16); --ak-on:#1A0F08; --ak-mine:#5A2A10; --ak-wash:#A8552A;
}}
:root:where([data-theme=dark]){
  --ak-acc:#F0A57A; --ak-soft:rgba(240,165,122,.16); --ak-on:#1A0F08; --ak-mine:#5A2A10; --ak-wash:#A8552A;
}

For LLMs and Kit builders

The same rules as a compact file for machines: guidelines.md (rule ids, token values, do and don't, components). Paste the block below into the system prompt of Claude, ChatGPT or any builder that writes Amili UI. Every rule on this page has a stable id (for example col-3) to cite.

Sources and versions

• Version 1.0, 2026-10-21. Rule ids are stable and only ever added; a retired rule keeps its id.
• Token values come from kit/brand-amili.mjs, which copies the app's own tokens; this page reads them when it is built.
• Inspired by the structure and principles of Apple's Human Interface Guidelines. Everything here is written for Amili, in our own words.
• Accessibility targets follow WCAG 2.2 level AA.