# Palette — full text

> Palette is a design language for interfaces where people and AI write together: three layers, four laws and fifteen live components, built mobile first by helikos.



---
URL: https://palette.helikos.dev/laws/
Palette
# Laws
AI now writes a growing share of what people read and act on in the browser. Four laws keep that work legible: who made it, whether it is still changing, what the AI may do next, and how to make it all stop.

## Why laws
Guidelines get traded off against each other. Laws hold on every screen. Palette has four because an AI-rich interface has four new questions to answer at a glance, and each law answers one of them.
AI is not a law. It is the reason for the laws. A screen that mixes a person’s words, an interface’s controls and a model’s output needs clear rules for telling them apart, for showing what the model is doing right now, and for showing what it will and will not do on its own. |
| Law | The question it answers | The rule
| 1 · Colour | Who made this? | Ink is the person’s, lapis is the interface’s, pigment is the model’s.
| 2 · Motion | Is it still changing? | Only the model’s live work moves. Settled content is still.
| 3 · Reach | What may the AI do here? | Every control shows what the model may do there, before it does it.
| 4 · Rest | How do I make it stop? | One shared beat. One Still switch stops everything.

## Law 1 · ColourThe rule
Ink is the person’s, lapis is the interface’s, pigment is the model’s.
Every screen has three authors, and each one gets its own layer of colour. Ink is everything a person wrote or chose. Lapis and the neutrals are the interface: controls, focus and structure. Pigment is everything the model wrote or proposed.
Pigment never turns into ink. When a person accepts what the model wrote, the pigment stops flowing and settles, but it stays pigment. The record of who wrote what survives acceptance, copying and saving.
Three state colours sit outside the layers: viridian for done, ochre for needs you, madder for errors. They mark outcomes, never decoration.
- Render model output in pigment from its first word. Don’t wait for it to finish.
- Keep accepted model text in still pigment. Acceptance changes motion, not authorship.
- Use solid tyrian where a gradient can’t be drawn: outlines, strokes, small marks and focus rings around model regions.
- Never use pigment for branding, headings or decoration. If it isn’t the model’s, it isn’t pigment.
Do: Keep accepted model text in still pigment, so its origin stays visible.
Don’t: Don’t turn model text into ink when a person accepts it. Nobody can tell who wrote it any more.

## Law 2 · MotionThe rule
Only the model’s live work moves. Settled content is still.
Motion is a signal, and a signal that never stops means nothing. In Palette, movement means the model is working: thinking, writing, or waiting for a person to review what it wrote. When the work settles, the motion stops.
The interface may respond to touch with brief motion: a sheet sliding up, a button settling back. Responses last one signal (280 ms) and play once. Nothing loops for decoration. |
| What | Moves? | How
| Model thinking | Yes | The model caret blinks; the model mark turns
| Model writing | Yes | Words arrive behind a steady model caret
| Model output awaiting review | Yes, slowly | Pigment flows once per beat
| Accepted model output | No | Still pigment
| Interface response | Briefly | One signal, 280 ms, once
| Decoration | Never | —
Do: Show thinking with the model caret, in the place the answer will appear.
Don’t: Don’t stack spinners, shimmering placeholders and animated gradients. Three motions say nothing about which one is the model.

## Law 3 · ReachThe rule
Every control shows what the model may do there, before it does it.
People need to know what the AI will and won’t do before it does it. Every control, field and region declares its reach with one of three marks, placed before its label. |
| Mark | Reach | Meaning
| Empty ring | Person only | Only a person may press or write here. The model can’t, even when asked.
| Half ring | Model prepares | The model may fill it in or set it up. A person confirms.
| Full ring | Model may act | The model may do this on its own, and says so when it has.
Actions that can’t be undone are person only. They seal with a one-beat hold (Seal), and the largest need two different people (Quorum). Fields declare reach the same way, and each writer has a caret in its own colour (Caret).
Marks tell people what to expect. They don’t enforce anything. Enforce reach on the server, for example with a passkey check for sealed actions, because an agent driving a real browser produces genuine presses.
Do: Mark every action, including the ones the model can’t take.
Don’t: Don’t leave reach to guesswork. Unmarked buttons make every action look equally safe to delegate.

## Law 4 · RestThe rule
One shared beat. One Still switch stops everything.
Every moving part keeps the same tempo: one beat of 2.4 seconds. A shared beat makes several live components read as one calm system instead of competing rhythms.
Motion has a cost. On an earlier Palette board with every component moving, the browser’s main thread stayed about 22% busy; with Still on, about 1.5%. So canvases share one clock, rest when their work is done, and sleep when they scroll off screen.
Still stops all motion in one switch, in the top bar and in Settings. It turns on by itself when a device asks for reduced motion. With Still on, every state must stay readable through colour, shape and words alone.
- Run every animation on the shared clock and let it rest. Return to stillness when the work is done.
- Keep three components or fewer in signal motion per screen.
- Pause anything off screen, including CSS animations on pseudo-elements.
- Test every component with Still on. If a state disappears without motion, give it a shape or a word.

## Check a screen
Run these four checks on any screen before you ship it. |
| Check | Law
| Point at any piece of text. Can you tell whether a person or the model wrote it? | Colour
| Does anything move that isn’t the model’s live work, or a brief response to touch? | Motion
| Does every button and field show whether the model may use it? | Reach
| Turn on Still. Does everything stop, and can you still read every state? | Rest

## RelatedColourThree inks for three authors: ink for people, lapis for the interface, pigment for the model.MotionOne tempo, what may move, and what motion costs.MarksReach marks, the model mark and the model caret.AccessibilityStill, contrast, screen readers, keyboard paths and text size.NextColourFoundations

---
URL: https://palette.helikos.dev/foundations/
Palette
# Foundations
The tokens and rules underneath every component: colour, type, motion, layout, marks, writing and accessibility.ColourThree inks for three authors: ink for people, lapis for the interface, pigment for the model.TypographyThree families, one scale, and how model text stays readable.MotionOne tempo, what may move, and what motion costs.LayoutMobile first: thumb zones, safe areas, grids and spacing.MarksReach marks, the model mark and the model caret.WritingTwo voices on one screen: the interface’s and the model’s.AccessibilityStill, contrast, screen readers, keyboard paths and text size.TokensEvery colour, type, space, form and motion token, resolved live.

---
URL: https://palette.helikos.dev/foundations/colour/
Foundations
# Colour
Colour in Palette carries authorship first. Three inks map to three authors, three state colours map to outcomes, and nothing is coloured for decoration.

## Three inks
Each author on the screen has its own ink. Use them by role, never by taste.Ink--inkThe person: their words, caret and choicesLapis--lapisThe interface: controls, focus, linksPigment--pigmentThe model: everything it writes or proposes
- Ink is the darkest neutral in light mode and the lightest in dark mode. Only people’s content and primary text use it.
- Lapis marks what you can operate: links, toggles, focus rings and the selection in a list.
- Pigment marks the model. It is the only gradient in the system.

## Pigment
Pigment runs through four hues (lapis, tyrian, madder and viridian) at one locked lightness: 0.50 in light mode and 0.76 in dark mode, in OKLCH. Only the hue moves, so contrast stays constant while the colour flows.
Pigment has two states. Flowing means the model is writing, or its work is waiting for a person. Still means a person accepted it. Accepted model text never turns into ink.Pigment--pigmentText and fillsPigment, vertical--pigment-vRails and edgesPigment, round--pigment-cThe model markTyrian--tyrianSolid pigment: strokes, outlines, small marks
Live demo: this sentence is flowing pigment, and this one was accepted.
Use solid tyrian wherever a gradient can’t be drawn: one-pixel strokes, outlines around model regions, the agent’s cursor and canvas lines.

## State colours
Three colours mark outcomes. Each one always pairs with a word or a shape, so it reads without colour too.Viridian--viridianDone, valid, approvedOchre--ochreNeeds you: a decision is waitingMadder--madderError, refused, rejected
- Don’t use state colours for categories, charts or decoration. A green that isn’t “done” teaches people to ignore green.
- Pair every state colour with a word or a mark: a flag, a tick, a struck value.

## Grounds and surfaces
The interface sits on warm paper in light mode and deep blue-black in dark mode. Surfaces step up in small increments; lines separate them.Ground--groundThe pageSurface--surfaceCards, sheets, fieldsSurface 2--surface-2Wells, segmented controlsLine--lineDividers and outlinesInk 2--ink-2Secondary textInk 3--ink-3Labels and captions

## Contrast
Every text colour meets WCAG AA (4.5:1) on the ground and on surfaces, in both modes. Pigment is the hard case, because a gradient is only as legible as its lightest stop. |
| Colour | Light, on ground | Dark, on ground
| Ink | 17.1 : 1 | 17.2 : 1
| Ink 2 | 6.5 : 1 | 8.6 : 1
| Ink 3 | 4.8 : 1 | 4.7 : 1
| Pigment, weakest stop | 4.8 : 1 (viridian) | 8.6 : 1 (tyrian)
| Tyrian | 5.8 : 1 | 7.9 : 1
| Madder | 5.1 : 1 | 7.4 : 1
| Ochre | 4.7 : 1 | 11 : 1
Pigment text uses a weight of 560 to 600. Thin strokes break a gradient into specks.

## Dark mode
Dark mode keeps every hue and swaps lightness. Pigment rises to 0.76 lightness with slightly less chroma, so it glows without vibrating against the dark ground. Shadows deepen; lines replace most of the elevation.
- Design both modes at once. Every token has a dark value; never hard-code a colour.
- Check pigment on the darkest surface you use, not only on the ground.

## Best practices
Do: Outline a model region in tyrian when its contents can’t be pigment, such as a chart or an image.
Don’t: Don’t use pigment for a heading because it looks good. People will read it as model-written.

## RelatedLawsColour, motion, reach and rest: the four rules every component follows.FluxText that shows the model wrote it: flowing until accepted, still pigment after.ProvenanceTokensEvery colour, type, space, form and motion token, resolved live.AccessibilityStill, contrast, screen readers, keyboard paths and text size.PreviousLawsStartNextTypographyFoundations

---
URL: https://palette.helikos.dev/foundations/typography/
Foundations
# Typography
Three families do three jobs: a display face with character for titles, a quiet grotesque for reading, and a mono for labels, values and code. One scale, set in rem, grows with the reader’s text size.

## Families |
| Family | Token | Use
| Bricolage Grotesque | --f-display | Titles, numbers that matter, the wordmark. Variable width and optical size.
| Hanken Grotesk | --f-body | Reading text, controls, fields and model output.
| JetBrains Mono | --f-mono | Labels, keys, values, units and code.
Model output is set in the body family at the size of the text around it. Authorship is carried by colour, never by a different typeface or italics.

## Scale
Each step has one job. Sizes that depend on the screen use clamp(), so a title fits a 390 px phone and still has presence on a desktop.--t-hero · Wordmark, shown at half size · palette--t-large · Page title · Large title--t-1 · Section title · Every screen has three authors--t-2 · Heading · Best practices--t-3 · Subheading · Card title--t-body · Body · The tenant may end the lease at year three.--t-callout · Callout · Fields, buttons and list rows.--t-sub · Subhead · Supporting text in cards and tables.--t-foot · Footnote · Notes, captions and chips.--t-cap · Caption · Timestamps and fine print.

## Model text
Pigment is a gradient laid over text, so it needs strokes thick enough to carry colour.
- Set model text at weight 560 to 600 in body sizes, and 700 or more in titles.
- Keep model text at the same size and family as the person’s text beside it. A model reply isn’t a different kind of writing; it has a different author.
- Don’t italicise model text. Italics already mean emphasis, titles and foreign words.
- Use tabular figures wherever model values sit in columns, so changed numbers don’t jostle their neighbours.
Do: Same family, same size, pigment for the model’s words.
Don’t: Don’t mark model text with a light italic serif. It reads as a quote, and grey reads as less important.

## Text size
Every size in Palette is in rem, so the whole interface scales with the reader’s choice. Settings offers three sizes: 100%, 112% and 125%. Layouts reflow; nothing is clipped.
- Never set text in px. Spacing in px is fine; text in px ignores the reader.
- Test every screen at 125% on a 390 px phone.
- Keep reading measure near 44 rem (about 70 characters). Long lines tire the eye; short ones break model text into fragments.

## RelatedColourThree inks for three authors: ink for people, lapis for the interface, pigment for the model.WritingTwo voices on one screen: the interface’s and the model’s.TokensEvery colour, type, space, form and motion token, resolved live.PreviousColourFoundationsNextMotionFoundations

---
URL: https://palette.helikos.dev/foundations/motion/
Foundations
# Motion
Motion in Palette means the model is working. Everything else is still, or moves once in response to a touch. One beat keeps every moving part in step, and one switch stops them all.

## One tempo |
| Token | Value | Use
| --beat | 2400ms | Signal motion: the model thinking, writing, or waiting for review. Holds that seal an action last half a beat.
| --signal | 280ms | Interface responses: sheets, buttons, page transitions. Once, then still.
| --ease-flow | | Movement that starts and settles: sheets, scenes.
| --ease-out | | Responses to touch: they start fast and land softly.
| --ease-spring | | Things that appear: murmurs, the ring keyboard. A small overshoot, never a bounce.

## What may move |
| State | Motion | Components
| The model is thinking | The model caret blinks; the model mark turns | Caret, Tide
| The model is writing | Words arrive behind a steady model caret | Flux, Murmur
| Model work awaits review | Pigment flows once per beat | Flux, Rail
| The model changed something | One pulse where it landed, then still | Shift
| A person touches something | One response of 280 ms | Morph, sheets
| Settled content | None | Everything

## Budget
Motion costs battery and attention. On an earlier Palette board with every component moving at once, the browser’s main thread stayed about 22% busy. With Still on it fell to about 1.5%, and moving off-screen animations to sleep took them to zero.
- Keep three components or fewer in signal motion per screen.
- Draw on the shared clock. A component that returns false rests until something wakes it.
- Sleep anything off screen: canvases stop drawing and CSS animations pause, including on pseudo-elements.
- Prefer motion that ends. A summary that plays once and rests (Reel) costs a few seconds; a looping one costs the whole visit.

## Moving between pages
Pages slide in the direction you travel: forward pushes from the right, back returns from the left, in one signal. The top bar and dock stay put, and a page’s pictogram carries across into its title. With Still on, pages change in place.

## Still
Still stops all motion: the top bar’s pause button and Settings both switch it, and it turns on by itself when a device asks for reduced motion. Still is not a degraded mode. Every state must stay readable through colour, shape and words.
Test with Still on first. If a state only exists while it moves, such as a shimmer that means “loading”, it needs a word or a shape too.

## RelatedLawsColour, motion, reach and rest: the four rules every component follows.AccessibilityStill, contrast, screen readers, keyboard paths and text size.TideA field whose edge shows what the model is doing.InputReelA model summary that plays once, like a short film.FeedbackPreviousTypographyFoundationsNextLayoutFoundations

---
URL: https://palette.helikos.dev/foundations/layout/
Foundations
# Layout
Palette is designed on a 390 px phone first and enhanced for larger screens. Controls live where a thumb can reach them, content stays at a readable measure, and every size follows a 4 px grid.

## Mobile first
Start every screen at 390 px wide, held in one hand. Add columns as the screen grows; never remove features to make a phone fit. |
| Width | Layout
| Under 640 px | One column. Top bar and dock. Sheets rise from the bottom.
| 640 px and up | Wider gutters. Grids gain columns.
| 1024 px and up | A sidebar holds navigation. Sheets become centred panels or slide in from the side.
| 1280 px and up | A table of contents follows the page.

## The thumb zone
On a phone, the bottom third of the screen is the easiest to reach. Put what people do there, and what they read above it.
- The dock holds the three global actions (index, ask, X-ray) at the bottom, and tucks away while you read down.
- Sheets open from the bottom and close with a downward swipe.
- The Ring keyboard’s button appears where your thumb last touched, not in a fixed corner.
- Murmurs appear just above the dock, where your thumb already is.
Do: Put the primary action at the bottom, inside the thumb’s reach.
Don’t: Don’t park the primary action in the top corner. It is the hardest place to reach one-handed.

## Spacing
Every space is a step on a 4 px grid, from --s-1 (4 px) to --s-11 (96 px). Gutters grow with the screen: 20 px on phones, 28 px from 640 px, 40 px from 1024 px. |
| Token | Value | Typical use
| --s-2 | 8 px | Between a mark and its label
| --s-3 | 12 px | Between chips and between cards
| --s-4 | 16 px | Inside cards and fields
| --s-6 | 24 px | Between paragraphs and blocks
| --s-9 | 56 px | Between sections

## Touch targets
- Make every target at least 44 by 44 px. Primary actions get 48 px or more.
- Leave 8 px between neighbouring targets, so a thumb can’t press two.
- Keep hold-to-confirm targets large: a sealed action should be a full-width row or a big ring.

## Safe areas
Palette fills the whole screen when installed, under the status bar and the home indicator. The top bar, dock, sheets and Ring keyboard all respect the safe-area insets, so nothing sits under a notch or a gesture bar.

## Measure
Reading text stops at 44 rem, about 70 characters. Specimens, tables and grids may run wider; prose doesn’t. On large screens the sidebar and table of contents take the extra width instead of the lines.

## RelatedTypographyThree families, one scale, and how model text stays readable.RingA compact circular keyboard on demand, built for one-thumb swiping.InputMurmurThe snackbar for model work: it streams, proposes and undoes.FeedbackPreviousMotionFoundationsNextMarksFoundations

---
URL: https://palette.helikos.dev/foundations/marks/
Foundations
# Marks
Four small marks carry most of the meaning in Palette: three reach marks that say what the model may do, and the model mark that says the model is here.

## Reach marks
A reach mark sits before a control’s label and says what the model may do with it. The shapes differ, not only the colours, so they read in greyscale and with Still on. |
| Mark | Name | The model may… | Example
| | Empty ring | Nothing. Person only. | Release a deposit, sign a lease
| | Half ring | Prepare it for a person to confirm. | Book a viewing, fill in a form
| | Full ring | Do it on its own, and report it. | Draft a reply, summarise a clause
- Mark every action in a screen that the model can see, including the ones it can’t take.
- Put the mark before the label, 8 px from it. The mark is part of the button, not a badge beside it.
- Use the same mark in a field’s header to say who may write in it.

## The model mark
The model mark is a disc of pigment. It labels model regions: a summary, a murmur from the model, the guide’s answers, the dock’s Ask button. It turns only while the model is working, and rests when it is done.
- Place it at the start of a model region, aligned with the first line.
- Don’t use it as a generic “AI” badge on features. It marks output, not marketing.

## Carets
Each writer has a caret in its own colour. The person’s caret is the system caret, in ink. The model’s caret is a bar of pigment: it blinks while the model thinks, holds steady while it writes, and leaves when it is done. A field that only the model writes has no ink caret at all.
See both carets in one field in Caret.

## The agent cursor
When an agent operates the interface, its cursor is drawn in tyrian with an “agent” label, so people can see what it is pointing at. It never borrows the person’s cursor.

## RelatedLawsColour, motion, reach and rest: the four rules every component follows.SealButtons that show what the model may press; irreversible ones need a hold.ActionsCaretFields that show who may write in them, with a caret in each writer’s colour.ProvenanceX-rayReveal what the model can read, write and do on any screen.SystemPreviousLayoutFoundationsNextWritingFoundations

---
URL: https://palette.helikos.dev/foundations/writing/
Foundations
# Writing
Two voices share every screen. The interface names things and actions plainly. The model says what it did, why, and what it needs from you. Neither one pretends to be a person.

## The interface’s voice
- Name the action and its object: “Approve invoice”, “Release deposit”. Never “OK” or “Submit”.
- Use sentence case everywhere, including buttons and titles.
- Write labels as nouns and actions as verbs. Keep both under four words.
- Say what happens when it matters: “Pays the tenant · cannot be undone · notifies finance”.

## The model’s voice
- Report what it did, in the past tense: “Minutes drafted: 6 decisions, 11 actions.”
- Give the reason for every change, with its source: “Renewal signed 2 Oct at S$9.20 psf.”
- Ask as a question with answers: “Offer the tenant a break option?” with “At year 3” and “No break”.
- State limits plainly: “Only a person can release the deposit.”
- Don’t claim feelings or opinions. No “I’m happy to help” and no “I think”.
- Refer to it as “the model” in interface text. Product and vendor names change; the role doesn’t.
Do: Say what changed, why, and what else it touched.
Don’t: Don’t perform enthusiasm or hide the change behind “optimised”.

## Murmurs and notices |
| Kind | Form | Example
| Done | Past tense, the object in bold | 38 invoices approved for payment
| Proposal | A question, with the action as its button | Move the lender call to 21 Oct? · Move it
| Refusal | What was refused, and who can do it | Refused · only a person can seal this
| Provenance | Who wrote it, after acceptance | Summary accepted · still marked as model-written

## Numbers, dates and money
- Write currency with its symbol and no space: S$48,200. Abbreviate millions as S$2.4M.
- Write dates as day and short month: 13 Oct, 1 March. Add the year only when it isn’t this year.
- Keep units next to values: S$9.80 psf, 1,850 sqm.
- Show changed numbers with the old value struck beneath the new one, never only the new one.

## RelatedTypographyThree families, one scale, and how model text stays readable.MurmurThe snackbar for model work: it streams, proposes and undoes.FeedbackAskThe model asks with a few answers instead of an empty box.InputAskingAsk people for decisions, and let them ask the model about anything.PreviousMarksFoundationsNextAccessibilityFoundations

---
URL: https://palette.helikos.dev/foundations/accessibility/
Foundations
# Accessibility
Provenance and reach have to work without sight, without motion and without a pointer. Every colour cue pairs with a word or a shape, every live region speaks once, and every gesture has a keyboard path.

## Still and reduced motion
Still stops every animation in the app. It turns on by itself when the device asks for reduced motion, and people can switch it from the top bar or Settings at any time.
- Never encode a state only in motion. Thinking has a blinking caret and a word; with Still on, the word remains.
- Streamed text arrives whole when Still is on.

## Contrast
All text colours meet 4.5:1 on their backgrounds in both modes, including pigment at its lightest stop. See Colour for the figures.

## Screen readers
- Announce model output once, when it is complete. Mark the region aria-busy while words stream in, so screen readers don’t read every word as it lands.
- Say who wrote it. Pigment is invisible to a screen reader, so label model regions in words: “Lease summary, written by the model”.
- Give reach in the accessible name or description: “Release deposit. Person only. Cannot be undone.”
- Announce changes the model made in one sentence: “The model changed 4 values in the rent roll.”
Palette routes announcements through a single polite live region, so two components can’t talk over each other.

## Keyboard paths |
| Component | Gesture | Keyboard
| Morph | Drag in a direction | Arrow keys choose, Enter applies
| Seal | Hold for one beat | Hold Space or Enter
| Caret | Tap to take the draft | Tab takes all, → takes one word
| Reel | Tap the sides, hold to pause | ← and → change scene, Space pauses
| Lasso | Select text | Select with Shift and the arrows, then Tab to the actions
| Guide | Tap Ask in the dock | ⌘K or Ctrl+K

## Text size
Every size is in rem. Settings offers 100%, 112% and 125%, and layouts reflow at each one. Browser zoom works too.

## Gestures
- Every swipe has a button: murmurs can be swiped, and also have their actions as buttons.
- The Ring keyboard is an addition, never a replacement. Hide it and the system keyboard returns.
- Holds can be cancelled by letting go early. Nothing happens until the hold completes.

## RelatedMotionOne tempo, what may move, and what motion costs.ColourThree inks for three authors: ink for people, lapis for the interface, pigment for the model.LawsColour, motion, reach and rest: the four rules every component follows.PreviousWritingFoundationsNextTokensFoundations

---
URL: https://palette.helikos.dev/foundations/tokens/
Foundations
# Tokens
Every colour, size, space, form and tempo in Palette is a CSS custom property. The values below are read live from this page, so they change when you switch theme or text size. Tap a token to copy it.

## Colour |
| Token | Value now | Use
| --ink | | The person’s layer: their text and choices
| --ink-2 | | Secondary text
| --ink-3 | | Labels and captions
| --lapis | | The interface’s layer: controls and focus
| --pigment | | The model’s layer: text and fills
| --tyrian | | Solid pigment for strokes and outlines
| --viridian | | Done
| --ochre | | Needs you
| --madder | | Error
| --ground | | The page
| --surface | | Cards, sheets and fields
| --surface-2 | | Wells
| --line | | Dividers
| --ink-l | | Pigment lightness, locked per theme
| --ink-c | | Pigment chroma, locked per theme

## Type |
| Token | Value now | Use
| --f-display | | Titles and key numbers
| --f-body | | Reading text and controls
| --f-mono | | Labels, values and code
| --t-hero | | The wordmark
| --t-large | | Page titles
| --t-1 | | Section titles
| --t-2 | | Headings
| --t-3 | | Subheadings
| --t-body | | Body text
| --t-callout | | Controls
| --t-sub | | Supporting text
| --t-foot | | Footnotes
| --t-cap | | Captions

## Space and form |
| Token | Value now | Use
| --s-1 | | 4 px step
| --s-2 | | 8 px step
| --s-3 | | 12 px step
| --s-4 | | 16 px step
| --s-6 | | 24 px step
| --s-8 | | 40 px step
| --s-11 | | 96 px step
| --gutter | | Page edge, grows with the screen
| --measure | | Reading width
| --r-sm | | Fields and rows
| --r-md | | Cards and tables
| --r-lg | | Large cards and sheets
| --r-pill | | Chips and capsules

## Elevation |
| Token | Value now | Use
| --e-1 | | Resting cards
| --e-2 | | Raised cards and specimens
| --e-3 | | Sheets, murmurs and menus
| --glass | | Bars over content

## Motion |
| Token | Value now | Use
| --beat | | Signal motion: the model’s live work
| --signal | | Interface responses
| --ease-flow | | Start and settle
| --ease-out | | Touch responses
| --ease-spring | | Arrivals

## Using tokens
Read tokens with var() and never copy their values. Dark mode, text size and future versions change the values, not the names.
Palette’s tokens are scoped to helikos apps. Emerra keeps its own theme.

## RelatedColourThree inks for three authors: ink for people, lapis for the interface, pigment for the model.TypographyThree families, one scale, and how model text stays readable.MotionOne tempo, what may move, and what motion costs.PreviousAccessibilityFoundationsNextProvenancePatterns

---
URL: https://palette.helikos.dev/patterns/
Palette
# Patterns
Recurring situations in AI-rich interfaces, and the components that solve them together.ProvenanceShow who wrote what, before and after a person accepts it.StreamingShow live model output without moving the page under the reader.ReviewAccept, edit or reject what the model drafts, a word or a section at a time.DelegationHand work to an agent, see what it did, and take it back.ConfirmationSeal actions that can’t be undone, so only people can take them.AskingAsk people for decisions, and let them ask the model about anything.

---
URL: https://palette.helikos.dev/patterns/provenance/
Patterns
# Provenance
People need to know who wrote what: before they accept it, after they accept it, and long after it has been copied into a report. Provenance keeps authorship visible for the life of the content.

## When you need it
- The model drafts text that a person will send, sign or publish under their own name.
- A document mixes a person’s writing with sections the model wrote.
- The model changes values in a table, and someone will make decisions from that table.

## How it works |
| Moment | What people see | Component
| The model is writing | Pigment text behind a steady model caret | Flux
| The draft awaits review | Pigment that flows once per beat | Flux
| A person accepts it | The pigment stops flowing, and stays pigment | Flux
| Both write in one field | Ink runs and pigment runs, side by side | Caret
| A long document | A scrollbar mapping every author | Rail
| Data the model changed | New value in pigment, old value struck beneath | Shift

## Best practices
- Keep provenance in the data, not only in the styles. Store who wrote each run of text, so it survives copy, export and reload.
- Never let acceptance erase authorship. Accepted means a person approved it, not that a person wrote it.
- When people edit model text, the edited words become ink and the untouched words stay pigment.
- Say it in words for screen readers and exports: “written by the model, accepted by Asvin, 13 Oct”.
Do: Show exactly which words the model wrote, even inside a sentence the person started.
Don’t: Don’t stamp a whole message “AI-assisted”. It tells people something happened, but not where.
Provenance is a record, not a warning. Model text isn’t worse text; it is text with a different author.

## RelatedFluxText that shows the model wrote it: flowing until accepted, still pigment after.ProvenanceCaretFields that show who may write in them, with a caret in each writer’s colour.ProvenanceRailA scrollbar that maps who wrote each part of a document.ProvenanceShiftTables that show what the model changed since you last looked.ProvenancePreviousTokensFoundationsNextStreamingPatterns

---
URL: https://palette.helikos.dev/patterns/streaming/
Patterns
# Streaming
Models write a word at a time. Streaming shows that work as it happens without moving the page under the reader, and without making a screen reader read every word.

## When you need it
- An answer takes more than a second to write.
- The model writes below the point the person is reading.
- Several model outputs are in progress at once.

## Three phases |
| Phase | Caret | Model mark | Screen reader
| Thinking | Blinks where the answer will appear | Turns | Region is busy
| Writing | Holds steady behind the last word | Turns | Region is busy
| Done | Gone | Rests | Reads the whole answer once
Thinking shows where the answer will land, so nothing jumps when it arrives. Writing keeps the caret still because the words themselves are the motion.

## Don’t move the reader
- Never scroll the page while the model writes. If new text lands below the fold, show a pill that offers to jump to it (Rail).
- Reserve space for short answers, so the layout doesn’t shift as words arrive.
- Let people keep reading, selecting and scrolling while the model writes.
Do: Offer a jump to new text and let the reader choose when to go.
Don’t: Don’t pin the scroll to the newest word. People lose their place in what they were reading.

## With Still on
Streaming is motion, so Still turns it off: answers appear whole when they are ready, and the thinking caret stays visible without blinking.

## RelatedFluxText that shows the model wrote it: flowing until accepted, still pigment after.ProvenanceMurmurThe snackbar for model work: it streams, proposes and undoes.FeedbackRailA scrollbar that maps who wrote each part of a document.ProvenanceMotionOne tempo, what may move, and what motion costs.PreviousProvenancePatternsNextReviewPatterns

---
URL: https://palette.helikos.dev/patterns/review/
Patterns
# Review
Everything the model drafts waits for a person. Review lets people accept, edit or reject it at the size that fits the decision: a word, a value, a section, or all of it at once.

## Choose the grain |
| Grain | Use | Component
| A word | Taking part of a suggestion while typing | Caret: → takes one word
| A passage | Accepting a summary or a reply | Flux
| A value | Keeping or reverting each change in a table | Shift
| A section | Accepting parts of a long document | Rail
| A queue | Triage: approve, reject, snooze or hand back | Morph

## The flow
- Draft. The model writes in flowing pigment. Nothing it wrote is final yet.
- Inspect. Changes show what they replaced; flags mark what needs a decision.
- Decide. Accept, edit, revert or reject, one item at a time or all at once.
- Settle. Accepted work stops flowing and stays pigment. Rejected work leaves no trace in the content.

## Best practices
- Always offer the undo. “Accept all” is fine when each item can still be reverted afterwards.
- Put the reason next to every change, with its source.
- Flag what needs a person in ochre, and say why: “Needs you · the heads of terms say 2.5%”.
- Move focus to the next pending item after each decision, so reviewing a long list takes one thumb.
Do: Show the old value beside the new one, and let people decide each change.
Don’t: Don’t overwrite a value and leave a footnote. Nobody can tell what it was, or why it changed.

## RelatedShiftTables that show what the model changed since you last looked.ProvenanceFluxText that shows the model wrote it: flowing until accepted, still pigment after.ProvenanceMorphOne button, five intents, chosen by the direction you drag.ActionsProvenanceShow who wrote what, before and after a person accepts it.PreviousStreamingPatternsNextDelegationPatterns

---
URL: https://palette.helikos.dev/patterns/delegation/
Patterns
# Delegation
Handing work to an agent should feel like handing it to a colleague: you know what they may do, you can watch them do it, and you can take it back.

## Before: say what the agent may do
Reach marks set expectations before anything happens. A screen where every control carries a mark answers the first question of delegation, “what will it touch?”, without a settings page. |
| Mark | The agent…
| Full ring | may do it and report it
| Half ring | may prepare it for you to confirm
| Empty ring | can’t do it, even when asked
Turn on X-ray to see the reach of a whole screen at once.

## During: show the agent at work
- Draw the agent’s cursor in tyrian, labelled “agent”, so people can see what it is pointing at.
- Turn the model mark in the dock while any agent is working, anywhere in the app.
- Report each completed step in a murmur, in the past tense, with an undo.

## After: take it back
- Keep an undo on every action the agent took, for as long as it is safe to reverse.
- Hand work back with one gesture: Morph’s upward drag hands an item to the agent, and the same control hands it back.
- Never let an agent seal what a person must seal. It can prepare the release; only a person holds it.
Agents that drive a real browser produce real clicks. Enforce person-only actions on the server, for example with a passkey, not only in the page.

## RelatedX-rayReveal what the model can read, write and do on any screen.SystemSealButtons that show what the model may press; irreversible ones need a hold.ActionsMorphOne button, five intents, chosen by the direction you drag.ActionsMurmurThe snackbar for model work: it streams, proposes and undoes.FeedbackPreviousReviewPatternsNextConfirmationPatterns

---
URL: https://palette.helikos.dev/patterns/confirmation/
Patterns
# Confirmation
Some actions can’t be undone: paying money, signing, deleting records. Palette seals them so only people can take them, and the biggest need two different people.

## Three levels |
| Level | Example | Pattern
| Undoable | Approve 38 invoices for payment run | Act now, offer undo in a murmur
| Irreversible | Release a S$48,200 deposit | Person only, hold one beat to seal (Seal)
| Irreversible and large | Draw down S$2.4M on a facility | Two people, each holds half (Quorum)
Prefer undo whenever the action allows it. A confirmation dialog interrupts every time; an undo costs nothing unless you need it.

## Sealing with a hold
- A hold takes half a beat (1.2 seconds). Letting go early cancels it, and nothing happens.
- The button fills as you hold, so the progress is visible and the release point is clear.
- State the consequences beneath the button: “Pays the tenant · cannot be undone · notifies finance”.
- Space and Enter hold too. Every hold has a keyboard path.
Do: Name the amount and the consequence on the control itself.
Don’t: Don’t ask “Are you sure?”. People learn to tap OK without reading.

## RelatedSealButtons that show what the model may press; irreversible ones need a hold.ActionsQuorumIrreversible actions that need two different people.ActionsMurmurThe snackbar for model work: it streams, proposes and undoes.FeedbackDelegationHand work to an agent, see what it did, and take it back.PreviousDelegationPatternsNextAskingPatterns

---
URL: https://palette.helikos.dev/patterns/asking/
Patterns
# Asking
Questions run both ways. The model asks people for decisions it can’t make alone, and people ask the model about anything on screen. Neither should start from an empty box.

## When the model asks
The model asks inline, at the point of need, with a few likely answers (Ask). Its question wears pigment; the answer stays in ink.
- Offer two to four answers, and “Other…” for anything else.
- Offer “You decide” only when the model’s choice is reversible, and mark its pick as the model’s.
- Keep a record of the answers so far above the question, so people can see the path they took.
Do: Ask a specific question with the likely answers ready to tap.
Don’t: Don’t ask an open question with an empty box. People have to work out what the model needs.

## When people ask |
| Ask about… | How | Component
| Anything on screen | Select it; the model’s actions gather beside it | Lasso
| Anything in the app | Tap Ask in the dock, or ⌘K | The guide
| A field | Type; the field’s edge shows the model’s state | Tide
Every answer cites where it came from. In this app, the guide answers from these pages on your device and pins each answer to the section it came from.

## RelatedAskThe model asks with a few answers instead of an empty box.InputLassoSelect anything and ask the model about it, right where it sits.InputTideA field whose edge shows what the model is doing.InputWritingTwo voices on one screen: the interface’s and the model’s.PreviousConfirmationPatternsNextFluxComponents

---
URL: https://palette.helikos.dev/components/
Palette
# Components
Fifteen live components. Each one follows all four laws and is built as a framework-free custom element.

## ProvenanceFluxText that shows the model wrote it: flowing until accepted, still pigment after.CaretFields that show who may write in them, with a caret in each writer’s colour.ShiftTables that show what the model changed since you last looked.RailA scrollbar that maps who wrote each part of a document.

## InputLassoSelect anything and ask the model about it, right where it sits.AskThe model asks with a few answers instead of an empty box.RingA compact circular keyboard on demand, built for one-thumb swiping.TideA field whose edge shows what the model is doing.

## ActionsMorphOne button, five intents, chosen by the direction you drag.SealButtons that show what the model may press; irreversible ones need a hold.QuorumIrreversible actions that need two different people.

## FeedbackMurmurThe snackbar for model work: it streams, proposes and undoes.ReelA model summary that plays once, like a short film.BloomDecoration that grows with the value it decorates.

## SystemX-rayReveal what the model can read, write and do on any screen.

---
URL: https://palette.helikos.dev/components/flux/
Components·Provenance
# Flux
Flux is text that shows the model wrote it. It flows in pigment while it waits for a person, settles into still pigment once accepted, and never turns into ink.
- Colour
- Motion

## Anatomy
- Person’s text: In ink. Written or chosen by a person.
- Model text: In pigment. Flows once per beat while it awaits review.
- Accept: Settles the pigment. Toggles, so acceptance can be undone.

## When to use
- Any text the model wrote that a person will read, send or sign: answers, summaries, replies, clauses.
- Inline, inside a person’s own sentence, when the model completed it.
- Not for the interface’s own words, such as labels and help text. Those are lapis and ink.

## Behaviour |
| State | Looks like | Means
| Writing | pigment behind a steady model caret | The model is still writing
| Flowing | pigment, flowing | Written, waiting for a person
| Still | pigment, still | A person accepted it
| Edited | Ink where the person changed words | The person rewrote part of it

## Best practices
- Mark model text from its first word, not after it finishes.
- Keep acceptance reversible for as long as the text hasn’t been sent.
- When a person edits model text, turn only the edited words into ink.
- Use a weight of 560 or more, so the gradient stays legible.
Do: Leave accepted text in still pigment.
Don’t: Don’t highlight model text with a background tint. It reads as a search match or a selection.

## Accessibility
- Pair the colour with words: the specimen’s status reads “Model-written · awaiting you”.
- The Accept control is a toggle button with aria-pressed.
- With Still on, flowing pigment stops but keeps its gradient, so authorship remains visible.

## Build it
Flux is pure CSS. Wrap model text in a span with the flux prov classes; add is-accepted when a person accepts it.
<span class="flux prov">4.1% ahead of budget</span>
<span class="flux prov is-accepted">…accepted…</span>
Flow: One cycle per beat (2.4 s), linear
Weight: 560 to 600 in body text
Tokens: --pigment, --beat
Off-screen: Paused

## RelatedProvenanceShow who wrote what, before and after a person accepts it.CaretFields that show who may write in them, with a caret in each writer’s colour.ProvenanceRailA scrollbar that maps who wrote each part of a document.ProvenanceColourThree inks for three authors: ink for people, lapis for the interface, pigment for the model.PreviousAskingPatternsNextCaretComponents

---
URL: https://palette.helikos.dev/components/caret/
Components·Provenance
# Caret
Caret makes every field say who may write in it, and gives each writer a caret in its own colour: ink for the person, pigment for the model. A field only the model writes has no ink caret at all.
- Colour
- Motion
- Reach

## Anatomy
- Person-only field: Empty-ring reach. Only the ink caret appears.
- Shared field: Half-ring reach. The model drafts ahead in flowing pigment.
- Take controls: Take one word or the whole draft. Mirror Tab and →.
- Model-only field: Full-ring reach. The model writes; people accept or ask for a rewrite.

## When to use
- A reply, note or message the model can help write.
- A field the model fills on its own, such as a summary, which people review but don’t type in.
- Not for passwords, amounts or anything a person must enter themselves: those fields are person only.
Caret is not autofill. Autofill copies values you stored. Caret writes from context and shows its hand: every word it adds stays pigment.

## Behaviour |
| Reach | Carets | What people can do
| Person only | Ink | Type
| Shared | Ink, and pigment ahead of it | Type, take a word, take the draft, dismiss with Esc
| Model only | Pigment | Accept or ask for a rewrite
The model caret blinks while it thinks, holds steady while it writes, and leaves when the draft is ready. Words taken from the draft settle into still pigment, so the field keeps a record of who wrote what.

## Best practices
- Put the reach mark in the field’s header, next to its name.
- Draft only at the end of the text and only when the person pauses. Never draft mid-word.
- Send the model’s caret back the moment the person types something else.
- If someone types in a model-only field, explain once in a murmur rather than ignoring the keys.
Do: Show the draft in flowing pigment after the person’s caret.
Don’t: Don’t show the draft in grey. Grey reads as a placeholder, not as another author.

## Accessibility
- The shared field’s label says how to take the draft: “Tab accepts its draft, right arrow accepts one word.”
- The model-only field is a read-only textbox labelled “written by the model”.
- Take controls are real buttons, so touch and switch users don’t need Tab or arrows.

## Specifications
Draft delay: 600 ms after the person pauses at the end of the text
Thinking: Model caret blinks for 700 ms
Writing: 50 to 110 ms per word
Keys: Tab takes all · → takes one word · Esc dismisses
Model caret: 2 px bar of pigment; blinks on the beat while thinking

## RelatedFluxText that shows the model wrote it: flowing until accepted, still pigment after.ProvenanceMarksReach marks, the model mark and the model caret.ProvenanceShow who wrote what, before and after a person accepts it.TideA field whose edge shows what the model is doing.InputPreviousFluxComponentsNextShiftComponents

---
URL: https://palette.helikos.dev/components/shift/
Components·Provenance
# Shift
Shift shows what the model changed in your data since you last looked. Each change lands with one pulse, wears pigment, keeps the old value struck beneath it, and waits until you keep or revert it.
- Colour
- Motion

## Anatomy
- Status: What the model did, and how many changes wait for you.
- Changed cells: New value in pigment, old value struck beneath it.
- Review bar: The reason and its source, with Revert and Keep.

## When to use
- Tables and records the model refreshes from another source: rent rolls, cash forecasts, schedules, registers.
- Any value people make decisions from, where a silent change would mislead.
- Not for live data that changes every second, such as prices. Those need a timestamp, not a review.

## Behaviour |
| Step | What happens
| Refresh | The status shows the model reading its source, with a thinking caret.
| Land | Each changed cell pulses once in tyrian, then rests. The new value flows in pigment.
| Inspect | Tapping a change shows its reason and source in the review bar.
| Keep | The value settles into still pigment. The struck value goes.
| Revert | The old value returns in ink. The change leaves no trace.

## Best practices
- Give every change a reason with a source and a date: “Renewal signed 2 Oct at S$9.20 psf”.
- Keep column widths stable. Use tabular figures so changed numbers don’t shift their neighbours.
- After each decision, move to the next pending change.
- Offer “Acknowledge all” only alongside per-change review, never instead of it.
Do: Keep the old value visible until a person decides.
Don’t: Don’t show only an arrow. People can’t tell what changed, by how much, or who changed it.

## Accessibility
- Changed cells are focusable buttons named in full: “L09 rent changed from 8.90 to 9.20. Renewal signed 2 Oct.”
- Old values carry a hidden “was” for screen readers.
- One announcement sums up the refresh: “The model changed 4 values in the rent roll.”

## Specifications
Landing pulse: One beat, once, in tyrian
Between changes: 420 ms
Old value: Ink 3, struck in madder at 70%
Figures: Tabular

## RelatedReviewAccept, edit or reject what the model drafts, a word or a section at a time.FluxText that shows the model wrote it: flowing until accepted, still pigment after.ProvenanceRailA scrollbar that maps who wrote each part of a document.ProvenanceWritingTwo voices on one screen: the interface’s and the model’s.PreviousCaretComponentsNextRailComponents

---
URL: https://palette.helikos.dev/components/rail/
Components·Provenance
# Rail
Rail is a scrollbar that maps authorship. Its track shows who wrote each part of a document and flags what needs you. It moves only while the model writes below the fold.
- Colour
- Motion

## Anatomy
- Document: Scrolls natively. Model sections carry a pigment edge.
- Track: One segment per section, coloured by author. Ochre dots flag decisions.
- Thumb: The visible part of the document, outlined in lapis.
- New-section pill: Appears when the model writes below the fold. Jumps there on tap.

## When to use
- Long documents written by people and the model together: leases, reports, minutes.
- Any scrolling region where people need to find what needs their decision.
- Not for short content that fits on one screen.

## Behaviour |
| Segment | Means
| Ink | A person wrote it
| Still pigment | The model wrote it and a person accepted it
| Flowing pigment | The model wrote it and it awaits review
| Ochre dot | A decision is needed here
| Glowing segment | The model is writing it now
Wheel, touch and keyboard scrolling stay native. The rail adds a map; it never replaces the scroll.

## Best practices
- Never scroll the reader to new text. Show the pill and let them choose.
- Flag a section only when it needs a person, and say why in the section itself.
- Keep the rail beside the content on every screen size; it is narrow enough for phones.

## Accessibility
- The rail is hidden from screen readers; the document itself carries the same information in words.
- The document is focusable and scrolls with the keyboard.
- Flags are dots and words, so they don’t depend on colour.

## Specifications
Width: 14 px rail, 3 px inset track
Minimum segment: Proportional to the section’s height
Motion: Only the segment being written flows
Thumb: 1.5 px lapis outline, 9% lapis fill

## RelatedStreamingShow live model output without moving the page under the reader.FluxText that shows the model wrote it: flowing until accepted, still pigment after.ProvenanceShiftTables that show what the model changed since you last looked.ProvenanceProvenanceShow who wrote what, before and after a person accepts it.PreviousShiftComponentsNextLassoComponents

---
URL: https://palette.helikos.dev/components/lasso/
Components·Input
# Lasso
Lasso lets people ask the model about anything on screen. Select words and the model’s actions gather beside the selection; the answer appears right there, in pigment.
- Colour
- Reach

## Anatomy
- Source: Any text the model may read.
- Action bar: Appears beside the selection, with the model mark and three or four verbs.
- Answer: Streams in pigment under the question, with Keep and Discard.

## When to use
- Documents, contracts, reports and tables where people need explanations in context.
- Instead of a chat panel that makes people copy and paste what they want to ask about.
- Not inside fields people are typing in. There, the system’s own selection menu wins.

## Behaviour |
| Pointer | Bar position
| Mouse | Above the selection
| Touch | Below the selection, clear of the system’s own menu
The bar offers verbs that fit the content: a clause gets Explain, Summarise, Compare and Draft reply. The answer quotes what was selected, so it stays clear what it refers to.

## Best practices
- Offer three or four verbs. More turns the bar into a menu.
- Quote the selection in the answer’s header.
- Keep answers beside their source. Don’t send people to a separate chat.
- Let people keep an answer as a note, still marked as model-written.
Do: Gather a few verbs beside the selection.
Don’t: Don’t make people copy text into a chat box to ask about it.

## Accessibility
- Select with Shift and the arrow keys, then Tab reaches the bar.
- The bar is a toolbar named “Ask the model about the selection”.
- Answers stream into a live region that is read once, when complete.

## Specifications
Minimum selection: 3 characters
Offset: 8 px from the selection
Bar: Ink capsule, 38 px targets
Global Lasso: On every page except inside specimens and fields

## RelatedAskingAsk people for decisions, and let them ask the model about anything.AskThe model asks with a few answers instead of an empty box.InputFluxText that shows the model wrote it: flowing until accepted, still pigment after.ProvenancePreviousRailComponentsNextAskComponents

---
URL: https://palette.helikos.dev/components/ask/
Components·Input
# Ask
When the model needs a decision, Ask puts the question where the work is and offers a few answers instead of an empty box. The question wears pigment; your answer stays in ink.
- Colour
- Reach

## Anatomy
- Record: The answers so far. Yours in ink, the model’s picks in pigment.
- Question: The model mark and one specific question, in pigment.
- Answers: Two to four likely answers, “You decide” and “Other…”.

## When to use
- The model can’t continue without a person’s choice.
- A short sequence of decisions builds a result: an offer, a schedule, a filter.
- Not for free-form conversation. Use the guide or Lasso for that.

## Behaviour
- Each answer moves the record forward and shows the model preparing the next question.
- “You decide” hands one choice to the model. Its pick appears in pigment with a full-ring mark, so it stays visibly the model’s.
- “Other…” opens a short field for an answer of your own.
- The result streams in pigment and waits for Accept.

## Best practices
- Ask one thing at a time, in words the person would use.
- Order answers by likelihood, and put the model’s recommendation first only if you say so.
- Offer “You decide” only for reversible choices.
Do: One question, likely answers, and a clear hand-off.
Don’t: Don’t bundle four decisions into one open question.

## Accessibility
- Answers are a labelled group of buttons.
- The record has a label, “Your answers so far”, and reads in order.
- The result is a live region read once, when complete.

## Specifications
Answers: 2 to 4, plus “You decide” and “Other…”
Between questions: 700 ms with a thinking caret
Model pick: Pigment, with a full-ring mark

## RelatedAskingAsk people for decisions, and let them ask the model about anything.LassoSelect anything and ask the model about it, right where it sits.InputWritingTwo voices on one screen: the interface’s and the model’s.PreviousLassoComponentsNextRingComponents

---
URL: https://palette.helikos.dev/components/ring/
Components·Input
# Ring
Ring is a keyboard on demand. Select a field and a faint ring button appears by your thumb. Tap it and a compact circular keyboard opens there. Swipe through the letters of a word, or tap single keys.
- Colour
- Reach

## Anatomy
- Ring fields: Any field can opt in. Selecting one summons the ring button.
- Layout: QWERTY bent into a circle: digits on the top rim, Z–M on the bottom rim, Q–P and A–L as the lids of an eye, space in the pupil.

## When to use
- Short replies and search on phones, where one thumb does the typing.
- Fields where swiping common words is faster than tapping.
- Not for passwords, codes or anything that needs exact characters. Leave the system keyboard there.

## Behaviour |
| Moment | What happens
| Select a field | A faint ring button appears where your thumb last touched.
| Tap the button | The keyboard opens there; the system keyboard goes down; the field stays selected.
| Swipe | Your stroke is decoded into a word. Three suggestions sit above the ring; tap one to swap.
| Tap | Single keys type as usual, with completions for the word in progress.
| Backspace after a swipe | Removes the whole swiped word.
| Select anything else | The ring and its button go away.

## How swiping works
The stroke and every word’s ideal path through the key centres are resampled to 24 points. Each word is scored by position (where the stroke went) and by shape (how it turned), plus a small prior for common words. Words whose first or last letters are far from the stroke’s ends are skipped, so decoding stays fast on a phone.
Ring decodes on the device. Nothing you type is sent anywhere.

## Best practices
- Summon, never force. The ring is an option on top of the system keyboard.
- Keep the field in sight: the ring sits below the field, scrolls the page like a system keyboard, or sits above it.
- Return moves to the next ring field in the same form, or submits the form from its last field.

## Accessibility
- The ring is pointer-only by design. Keyboard and screen-reader users type as usual; the ring never takes a field away from them.
- Hiding the ring hands the field back to the system keyboard.
- Settings can turn the ring off for the whole app.

## Specifications
Diameter: 224 to 272 px, fitted to the screen
Ring button: 48 px, 60% opacity until touched
Tap vs swipe: Strokes shorter than 8% of the radius are taps
Suggestions: Three, best in the middle
Ink trail: The person’s stroke in ink, fading over 500 ms

## RelatedLayoutMobile first: thumb zones, safe areas, grids and spacing.TideA field whose edge shows what the model is doing.InputAccessibilityStill, contrast, screen readers, keyboard paths and text size.PreviousAskComponentsNextTideComponents

---
URL: https://palette.helikos.dev/components/tide/
Components·Input
# Tide
Tide is a field whose edge reports what the model is doing. It rests while idle, runs while the model thinks, stops dead on an error and settles into a solid line once valid. Each keystroke sends one ripple.
- Motion
- Rest

## Anatomy
- Field: An ordinary text field. The person types in ink.
- Edge: Drawn on the shared clock. Its shape and colour carry the model’s state.
- State label: The same state in words, for screen readers and Still.

## When to use
- Fields that send what you type to the model: ask boxes, smart search, prompts.
- Fields the model validates as you type.
- Not for ordinary form fields. A plain field with a focus ring is enough.

## Behaviour |
| State | Edge | Colour
| Idle | Still. Lapis while focused. | Lapis
| Thinking | Three packets travel the edge | Tyrian
| Error | A frozen wave | Madder
| Valid | Settles into a solid line | Viridian
The guide’s question field in this app is a Tide: it runs while the guide writes an answer.

## Best practices
- Only the thinking state loops, and only while the model works.
- Pair every state with words: “State: thinking”.
- Keep ripples small. They acknowledge typing; they don’t decorate it.

## Accessibility
- The edge is decorative to assistive tech; the state label is a polite live region.
- With Still on, the edge shows each state as a still shape and colour.

## Specifications
Edge: 2 px stroke, 12 px outside the field
Thinking: 3 packets, one lap every 3 s
Ripple: Decays over 1.4 s
Rest: Draws nothing while idle and unfocused

## RelatedCaretFields that show who may write in them, with a caret in each writer’s colour.ProvenanceMotionOne tempo, what may move, and what motion costs.StreamingShow live model output without moving the page under the reader.PreviousRingComponentsNextMorphComponents

---
URL: https://palette.helikos.dev/components/morph/
Components·Actions
# Morph
Morph is one button with five intents. Tap it for the primary action, or drag toward an edge to choose another. Each edge wears its action’s colour, and the chosen edge floods the button as you drag.
- Colour
- Reach

## Anatomy
- Button: Tap for the primary action. Its four edges are coloured by the action on that side.
- Approve, right: Viridian: the colour for done.
- Reject, left: Madder: the colour for refusal.
- Snooze, down: Ochre: it will need you again.
- To agent, up: Tyrian: hands the item to the model.

## When to use
- Triage queues where every item gets one of a few decisions: invoices, approvals, alerts.
- Mobile lists where a row of four buttons would crowd the screen.
- Not for irreversible actions. Morph acts on release; sealed actions need a hold.

## Behaviour |
| Gesture | Result
| Tap | The primary action: open the item
| Drag under 46 px | Preview: the edge thickens and its hint lights up
| Drag past 46 px | Commit on release: the edge floods the button and its label changes
| Release early | The button springs back. Nothing happens.
Every committed action shows a murmur with an undo.

## Best practices
- Keep the directions the same on every screen. Right always approves.
- Use state colours by meaning, not by preference.
- Label each direction around the button the first few times people use it.
Do: Colour each edge by the action on that side.
Don’t: Don’t hide directions behind a hint. People can’t tell what each way does.

## Accessibility
- Arrow keys choose a direction; Enter applies it; Escape cancels.
- The button’s name lists the choice: “Review invoice 214. Arrow keys choose an action, Enter applies it.”
- Each result is announced through its murmur.

## Specifications
Commit threshold: 46 px
Edges: 4 px at rest, up to 14 px when chosen
Travel: Up to 36 px sideways, 24 px vertically
Settle: 420 ms spring

## RelatedReviewAccept, edit or reject what the model drafts, a word or a section at a time.SealButtons that show what the model may press; irreversible ones need a hold.ActionsMurmurThe snackbar for model work: it streams, proposes and undoes.FeedbackPreviousTideComponentsNextSealComponents

---
URL: https://palette.helikos.dev/components/seal/
Components·Actions
# Seal
Seal makes buttons wear their reach. A full ring means the model may press it, a half ring means it may prepare it, and an empty ring means only a person may press it. Irreversible actions seal with a one-beat hold.
- Reach

## Anatomy
- Model may act: Full ring. The model can press this and reports when it has.
- Model prepares: Half ring. The model sets it up; a person confirms.
- Sealed action: Empty ring. Fills as you hold; seals after one beat.
- Consequences: What sealing does, in words, under the button.

## When to use
- Every button on a screen an agent can see. Reach marks belong on all of them.
- The hold for actions that can’t be undone: payments, releases, signatures, deletions.
- Not the hold for anything undoable. Act at once and offer undo instead.

## Behaviour |
| Button | A person | The agent
| Draft reply | Presses it | Presses it; a murmur reports it
| Book viewing | Presses it | Prepares it; a person confirms
| Release deposit | Holds it for one beat | Refused
The demo refuses the agent because its presses are page scripts, which the browser marks as untrusted. An agent driving a real browser produces trusted presses, so production systems must enforce sealed actions on the server, for example with a passkey check.

## Best practices
- Put the amount and the object in the label: “Hold to release S$48,200 deposit”.
- List the consequences under the button, separated by dots.
- Make sealed buttons full width on phones, so the hold is easy to keep.
Do: Say what a hold will do, and to what.
Don’t: Don’t make people hold a vague label. A hold is a promise; they need to know what they promise.

## Accessibility
- Holding Space or Enter seals with the keyboard.
- The consequences are linked as the button’s description.
- Refusals are spoken and shown in words: “Refused · only a person can seal this”.

## Specifications
Hold: 1.2 s, half a beat
Progress: 3 px ink bar filling left to right
Height: 52 px minimum
Marks: 10 px, 10 px before the label

## RelatedConfirmationSeal actions that can’t be undone, so only people can take them.QuorumIrreversible actions that need two different people.ActionsMarksReach marks, the model mark and the model caret.DelegationHand work to an agent, see what it did, and take it back.PreviousMorphComponentsNextQuorumComponents

---
URL: https://palette.helikos.dev/components/quorum/
Components·Actions
# Quorum
Quorum is for irreversible actions that need two different people. Each approver holds their half of the ring. The action seals only when both halves close, and an agent can hold neither.
- Reach

## Anatomy
- Your half: Fills clockwise from the top while you hold.
- Their half: Fills from the bottom while the second person holds, on their own device.
- Seal: The amount and the next step. Holds work with touch, mouse and keyboard.
- Approvers: Who must hold, and where each one is.

## When to use
- Four-eyes controls: drawdowns, large payments, write-offs, signing on behalf of a company.
- Any action your policy says one person may not take alone.
- Not for routine approvals. Two holds cost two people’s attention.

## Behaviour |
| Moment | Ring | Note
| Waiting | Empty track | Needs two people
| You hold | Your half fills over 1.2 s | —
| Your half sealed | Your half stays full | Waiting for the second approver
| They hold | Their half fills over 1.2 s | Holding on her phone
| Both sealed | The whole ring turns viridian | Released
| The agent tries | The ring shakes | Refused · an agent can’t hold either half

## Best practices
- Require two different people, each signed in on their own device.
- Show who holds the other half, and where they are in the process.
- Never let one person hold both halves, even with two accounts open.
Like Seal, Quorum states policy in the interface. The server enforces it: each half is a separate signed approval from a different person.

## Accessibility
- Hold Space or Enter to approve your half.
- Progress and refusals are announced through a polite live region.
- Each approver’s state is written out, not only drawn.

## Specifications
Ring: 168 px, 8 px stroke
Hold: 1.2 s per half
Your half: Ink
Their half: Ink 2
Sealed: Viridian

## RelatedSealButtons that show what the model may press; irreversible ones need a hold.ActionsConfirmationSeal actions that can’t be undone, so only people can take them.DelegationHand work to an agent, see what it did, and take it back.PreviousSealComponentsNextMurmurComponents

---
URL: https://palette.helikos.dev/components/murmur/
Components·Feedback
# Murmur
Murmur is the snackbar for model work. It streams what the model is writing, proposes actions before taking them, counts down its own life, and swipes away.
- Colour
- Motion

## Anatomy
- Model mark: On murmurs from the model. Turns only while it streams.
- Message: What happened or what the model proposes, with the object in bold.
- Actions: One or two. The last is the primary action.
- Life line: Counts down the murmur’s life. Pauses while you touch it.

## When to use |
| Kind | Use
| Stream | The model is writing something people will want to open or send.
| Propose | The model wants to act and needs a yes first.
| Undo | An action happened and can still be reversed.
Don’t use murmurs for errors that block work. Show those where the work is.

## Behaviour
- Three murmurs show at most. Older ones fold away.
- Swipe right to accept a proposal, left to dismiss.
- Streaming murmurs hold their countdown until the model finishes writing.
- Murmurs sit above the dock on phones, and at the lower right on large screens.

## Best practices
- Lead with the object: “Lender call moved to 21 Oct”.
- Give proposals a specific verb: “Move it”, not “OK”.
- Offer undo on every action the model took on its own.
Do: Ask before acting, with the action as the button.
Don’t: Don’t report a change without saying what changed or offering a way back.

## Accessibility
- Murmurs live in a polite live region and are read once complete.
- Every swipe has a button.
- Life pauses on hover, focus and touch, so nobody has to race the countdown.

## Specifications
Life: 3.5 to 12 s, by kind
Swipe: 90 px commits
Stack: 3 visible
Enter: 420 ms spring

## RelatedStreamingShow live model output without moving the page under the reader.MorphOne button, five intents, chosen by the direction you drag.ActionsWritingTwo voices on one screen: the interface’s and the model’s.PreviousQuorumComponentsNextReelComponents

---
URL: https://palette.helikos.dev/components/reel/
Components·Feedback
# Reel
Reel is a model-written summary that plays once, like a short film: subject, metric, trend, risk and next step. Then it rests on the next step.
- Motion
- Rest

## Anatomy
- Progress: One bar per scene.
- Scene: A label, one big value, and one line of context.

## When to use
- A briefing people glance at: an asset, a deal, a portfolio, a week.
- On a home screen or at the top of a record.
- Not for anything people must study. Use a table or a report.

## Behaviour |
| Scene | Content
| 1 · Subject | What this is about
| 2 · Metric | The number that matters, counted up once
| 3 · Trend | A line drawn once
| 4 · Risk | The one thing to watch, flagged in ochre
| 5 · Next step | The recommended action. The reel rests here.
Each scene lasts one beat. The reel plays once, then stops.

## Best practices
- Five scenes, one idea each.
- End on an action, not a statistic.
- Mark it as model-written in the first scene.
- Never loop. A summary that repeats becomes wallpaper.

## Accessibility
- ← and → change scene; Space pauses.
- Hidden scenes are hidden from screen readers; the visible one is read.
- With Still on, the reel shows one scene at a time and steps by hand.

## Specifications
Scene: 2.4 s, one beat
Total: 12 s, once
Ratio: 16 : 10
Pause: Hold for 280 ms

## RelatedMotionOne tempo, what may move, and what motion costs.BloomDecoration that grows with the value it decorates.FeedbackFluxText that shows the model wrote it: flowing until accepted, still pigment after.ProvenancePreviousMurmurComponentsNextBloomComponents

---
URL: https://palette.helikos.dev/components/bloom/
Components·Feedback
# Bloom
Bloom is decoration that grows with the value it decorates. Each branch is a finished milestone and blossoms in viridian, the colour for done. It is seeded from the record ID, so a record always grows the same plant.
- Colour
- Rest

## Anatomy
- Plant: Stems in ink 2, blossoms in viridian.
- Value: The number it decorates, always written out.
- Control: Here a slider. In a product, the record’s real value.

## When to use
- Values that accumulate: milestones, occupancy, collections.
- Places where a little delight is earned: a project page, a completed checklist.
- Not as a chart. Bloom shows progress, not precision; the number beside it does that.

## Behaviour
- Grows only when its value changes, then rests. It never loops.
- The same record ID always grows the same plant, so people recognise their own.
- With Still on, it draws the final plant at once.

## Best practices
- Always show the value in words beside the plant.
- Use viridian only for finished work.
- Keep it small. Bloom is a flourish, not a hero.

## Accessibility
- The plant is hidden from assistive tech; the value is the label.
- Its colours carry no meaning that the number doesn’t.

## Specifications
Branches: 63 at most, grown breadth first
Blossoms: On branches three deep or more
Growth: Eases 6% of the way per frame, then rests
Seed: The record ID

## RelatedReelA model summary that plays once, like a short film.FeedbackColourThree inks for three authors: ink for people, lapis for the interface, pigment for the model.MotionOne tempo, what may move, and what motion costs.PreviousReelComponentsNextX-rayComponents

---
URL: https://palette.helikos.dev/components/xray/
Components·System
# X-ray
X-ray reveals what the model can read, write and do on any screen. One switch outlines every region with its reach, so people can check an AI-rich screen before they trust it.
- Reach

## Anatomy
- Switch: Turns X-ray on for this screen. The dock’s eye does it for the whole app.
- Regions: Each region declares its reach. X-ray outlines and tags them.
- Legend: The five kinds of reach, in marks and words.

## Five kinds of reach |
| Reach | Outline | Meaning
| Model reads | Faint tyrian | The model can read this region
| Model writes | Solid tyrian | The model writes or rewrites here
| Model may act | Solid tyrian | The model may press this on its own
| Model prepares | Hatched tyrian | The model sets this up; a person confirms
| Person only | Ink | Only a person may use this

## Build it
Declare reach on any element with a data-reach attribute. X-ray reads the attributes; it doesn’t guess.
<section data-reach="read">…</section>
<div data-reach="write">Summary…</div>
<button data-reach="act">Draft reply</button>
<button data-reach="prepare">Book viewing</button>
<button data-reach="person">Sign lease</button>
The same attributes tell agents what they may do, so a page that X-rays well also reads well to an agent.

## Best practices
- Declare reach for every region an agent can see, not only for buttons.
- Keep the declared reach and the server’s rules in one place, so they can’t drift apart.
- Use X-ray in reviews: turn it on and check that nothing the model can touch is unmarked.

## Accessibility
- X-ray is announced when it turns on and off.
- The overlay is decorative; each control already carries its reach in its name.
- Escape turns it off.

## Specifications
Attribute: data-reach = read · write · act · prepare · person
Overlay: Fixed, below the top bar, never intercepts touches
Updates: On scroll, resize and route change

## RelatedDelegationHand work to an agent, see what it did, and take it back.Built for agentsHow this site reads to AI agents: prerendered pages, llms.txt and reach annotations.SealButtons that show what the model may press; irreversible ones need a hold.ActionsMarksReach marks, the model mark and the model caret.PreviousBloomComponentsNextBuilt for agentsResources

---
URL: https://palette.helikos.dev/resources/agents/
Resources
# Built for agents
Palette is written for two readers: the people who design with it, and the AI agents that read the web for them. Every page works without scripts, every region declares its reach, and the whole language fits in one text file.

## Real pages
Every page is prerendered as plain HTML with its title, description and structured data in place. Scripts add the live specimens and the app’s gestures; nothing is lost without them.
- One h1 per page, sections in order, and a table of contents.
- Stable addresses: every section has an anchor, such as /laws/#reach.
- A sitemap lists every page.

## llms.txt
/llms.txt indexes the whole language: the laws, every foundation, pattern and component, with a one-line summary each. /llms-full.txt holds the full text of every page in one file, ready to load into a model’s context.

## Reach in the markup
Every region declares what the model may do there with a data-reach attribute. People see the same declarations with X-ray. |
| Value | An agent may…
| read | Read it
| write | Write or rewrite it
| act | Press it
| prepare | Set it up for a person to confirm
| person | Nothing. Only a person may use it.
Reach in markup states intent. It doesn’t stop an agent that ignores it, so person-only actions must also be enforced on the server.

## The guide
Ask in the dock answers questions from these pages. It runs on your device: it ranks every passage on the site against your question, writes the answer in pigment, and pins each sentence to its source. No language model runs, and nothing you ask leaves your device.

## Offline and installable
Palette installs to a phone’s home screen and works offline once visited. Pages, styles and specimens are cached on first load and refreshed in the background.

## RelatedX-rayReveal what the model can read, write and do on any screen.SystemDelegationHand work to an agent, see what it did, and take it back.RoadmapComponents in design next, and what changed in each release.PreviousX-rayComponentsNextRoadmapResources

---
URL: https://palette.helikos.dev/resources/roadmap/
Resources
# Roadmap
Components in design next, and what changed in each release. Everything on this list follows the four laws before it ships.

## In design |
| Component | What it does | Laws
| Plan | Shows an agent’s plan as a checklist people can edit, reorder or strike before it runs. | Reach
| Wake | A trail of what an agent did, step by step, with an undo on each step that can still be undone. | Colour, Reach
| Pilot | Shared control: the agent drives with its own cursor while the person watches, and either can take over. | Reach, Motion
| Leash | A visible budget for an agent’s autonomy: steps, money and time it may spend before it must check in. | Reach
| Baton | Hands a task between person and agent with an explicit handover, so it is always clear who holds it. | Reach
| Fill | Form filling by the model, with each filled field marked and its source one tap away. | Colour, Reach
| Redline | Tracked changes for model edits to documents, word by word, accepted or rejected in place. | Colour
| Fork | Two or three model alternatives side by side; take whole options or merge parts of them. | Colour
| Pin | A source pin on any model claim that opens the cited passage in place. | Colour
| Tether | Keeps model output linked to the data it came from, and shows when that data has changed. | Colour, Motion
| Fade | Suggestions with a shelf life: they withdraw themselves when their context changes. | Motion, Rest
| Gauge | Shows how sure the model is as a range in words, never as a bare percentage. | Colour
The guide in this app already uses an early Pin: every answer pins to the section it came from.

## Changes |
| Version | Date | What changed
| 1.0 | Oct 2026 | Palette becomes an installable, mobile-first app. Documentation for every law, foundation, pattern and component. A guide that answers from these pages on your device, a global Lasso, and X-ray for every screen. New components: Shift, Quorum and X-ray. Contrast raised to AA for every text colour.
| 0.4 | 10 Oct 2026 | Morph colours each edge by its action. Seal states that sealed actions are enforced on the server.
| 0.3 | 10 Oct 2026 | The four laws and the three colour layers. New: Lasso, Ask, Caret, Rail and Seal.
| 0.2 | 9 Oct 2026 | Ring rebuilt as a keyboard on demand. Examples moved to finance and real estate.
| 0.1 | 9 Oct 2026 | The first board of primitives.

## RelatedLawsColour, motion, reach and rest: the four rules every component follows.ComponentsFifteen live components. Each one follows all four laws and is built as a framework-free custom element.Built for agentsHow this site reads to AI agents: prerendered pages, llms.txt and reach annotations.PreviousBuilt for agentsResources