Skip to main content
These are laws, not preferences. Each one was ruled by the founder on a dated Linear record, and each binds every Lucia surface: the admin, the docked Lucia panel, the Fieldwork app, guest mail, templates, fixtures, and this Library. Where a law is still being applied surface by surface, this page says so and names the evidence; it never writes a planned cut as landed.

​
1. The names: Lucia and Villa Valentin, plain i

Founder, 2026-09-09 (LUCI-238): “We want i. Always. Never í.” The names are written Lucia and Villa Valentin on every surface: sender names, templates, footers, fixtures, tool descriptions, copy, documentation. Never an acute. Where it stands on 2026-09-10: the sweeps landed on Engine dev d576a74, Admin dev 68e77be, and the Fieldwork API at 89b775b, each with a pin that fails on any acute in served copy (HLLC-41 audit read, 2026-09-10). One value is still open: the guest-verification sender name on the Development Engine is an environment value the founder changes by hand, and this pass did not read it. Until read, treat that live value as set by the founder’s hand, unverified.

​
2. No left accent bars

Founder, 2026-09-09 (LUCI-239): “This ‘left vertical bar’ is becoming a Claude Code default design element and I do not want it in Lucia. We have worked for months nonstop to customize the world-class nature of our UI. Get rid of it.” A card or step is set apart by its ground, its stroke, and its type, never by a coloured stripe down its left edge. The law applies to the admin, the docked panel, and the Fieldwork app. It joins the no-pill rule as a standing design law. Where it stands: removed from the payment record’s draft card and the admin stylesheet on Admin dev 18f976b, with a computed-style pin that no card in the payment record carries a heavier left border or a left-edge shadow (HLLC-41 audit read, 2026-09-10). The Fieldwork app and the docked panel take the same law on their next pass (LUCI-239).

​
3. No pills, and the one dress

Founder, 2026-09-09 (LUCI-249): “We need to get all of the interface elements to match. This is a linear style upgrade.” The one dress, as measured on Admin dev f2ff0f1 and recorded on LUCI-249:
The rule reaches guest mail too. On 2026-09-09 the founder ruled the guest-mail buttons “rectangles not pills with 4-5px rounded corners”, centred, same colours (LUCI-237); the magic-link and guest-agent buttons take the same shape because they are one family. Where it stands: LUCI-249 is the umbrella for a cut list, one child per admin surface. The ops shell, the sent line, the payment page dress pass, and the no-left-bars pass are on Admin dev; the remaining children were cut on 2026-09-10 and are in flight or waiting. A CI guard that fails the build on a new oversized radius (CI guards the dress, LUCI-260) closes the upgrade and was not built as of 2026-09-10. Read LUCI-249 for the live cut list; this page does not restate a status. Two exceptions are on record: the guest record’s bare top (section 4) and the docked panel’s round composer buttons (HLLC-41 audit, 2026-09-10).

​
4. The Masthead

Founder ruling, 2026-09-09, verbatim (LUCI-262):
Masthead: the housing itself, with the shared stroke, shadow and gold wash. Dashboard, Maintenance, Bookings and the payment record each have one. The guest record is the one page without a masthead, by your call. All pages require a uniform masthead housing unless otherwise ruled on by the founder. Masthead plane: the 77px line its top edge sits on, on every page. Masthead rule: the fading line under it, with 24px above and below.
The Masthead is the first housing on an admin page: a stroked, shadowed panel with the gold wash, carrying the page’s eyebrow or title and its standing line, opening the page under the topbar. It is not the topbar and it is not a card. The stroke is #ffc46c7a; the housing radius is 0.3rem; the words inside are owner vocabulary (LUCI-262). It supersedes the earlier names “top housing”, “header band”, “panel shell”, and “the plate”. Every new admin page opens with a Masthead on the plane with the rule beneath, unless the founder rules otherwise on that page’s record. Before touching a Masthead or adding a page, an agent reads LUCI-262, renders the new page top beside the Bookings top, and shows the founder before committing. The one ruled exception: the guest record keeps its bare top: guest name, stay line, status chip on the linen, readiness card beneath. “For some reason I feel like this is one that should stay this way.” (founder, 2026-09-09, on LUCI-240). No uniformity pass houses the guest record. Where it stands: the payment-record Masthead is on Admin dev at 17c3b06 and is pinned in code against the Bookings Masthead for plane, stroke colour, and the 24/24 rule (LUCI-262; HLLC-41 audit read, 2026-09-10). Naming the class masthead in code is a proposed follow-up, not done.

​
5. The light idiom and the registers

Light. The admin is a light, linen surface. Motion pieces are wired light-theme only, and the animated-icon law names the admin’s light/linen idiom (LUCI-222, LUCI-191). Owner words in the black sans. Everything the owner reads sits in the house sans on the linen, in owner vocabulary (section 6). JetBrains Mono is the machine-truth register. Ruled on 2026-08-25 (LUCI-165, completed): the mono face marks machine truth such as a state chip or a category chip, and extends only where the founder decides to spread it. It is never used for owner words. Typography tuning inside that register happens live on Admin dev with the founder’s verdict, not in a mock.

​
6. Owner language

Founder, 2026-09-02 (ALGO-29): “All engine/dev language replaced for real-world/human language that a property owner would understand.” Every owner-facing word on every Lucia surface follows the rules ratified on ALGO-29 (2026-09-03). The full rules R1 to R10 and the spoken-durations addendum are written out in Voice and Tone. In one line: name the guest, say when like an owner, name the thing, one plain sentence, no engine words, money in owner terms, uncertainty as what we do not know, labels are owner categories or nothing, Lucia speaks as a colleague, and Lucia never talks about proof. Where it stands: the served Signal Stream, Spotlight, and Focus strings and the admin display labels speak owner language on Development (Engine dev merges 48f2c2c, 5318c14, 12373f4; Admin dev 9fa5650 and after, 2026-09-03; ALGO-29). An owner-language scan rides the Engine battery with no exemptions.

​
7. How Lucia shows motion

Three in-flight faces, each meaning one thing (LUCI-222, LUCI-244):
Founder, 2026-09-09 (LUCI-244): “I liked the three dots we had before. Users are used to that. It’s a classic AI chat conversation animation. The composition orb was just to be used in the Lucia chat window when she’s accessed at the bottom of the page.” Never the orb in Focus; never the dots in the panel. Both are Motion Library recipes with one colour family and timing so they read as one Lucia. Adopt, never recreate. On 2026-09-07 the founder named an open-source orb library and ruled that a mechanism worth adopting is adopted, not rebuilt (LUCI-222). The in-flight face is wired to the panel’s real request state, never a timer, and honours reduced motion. Where it stands: the orb ships in the docked panel and the three dots in dashboard Focus on Admin dev 39793f3 (HLLC-41 audit read, 2026-09-10); LUCI-222 and LUCI-244 were In Review on that date.

​
The Lucia Orbit loader

The Lucia Orbit is the founder-ratified loader for any surface where Lucia’s avatar is the anchor: the brand-cycle tail around Lucia’s round headshot. It is documented at its source in the Fieldwork app repository (docs/lucia-orbit.md) and is the model for how every motion primitive is documented (LUCI-170). The Fieldwork cold open plays it; see the Fieldwork product pages for that surface. This Library carries the pointer, not the recipe.

​
The Lucia Motion Library

Founder, 2026-08-30 (LUCI-170): “Start it right away with what we know we’re using, and add to it as we continue to develop, so it’s easy to say ‘throw this in the motion library.’” The Lucia Motion Library is the company’s single searchable home for Lucia’s motion vocabulary: a search bar, a row or square per element with a title, and for each element the list of where in the platform it is used. Its ratified name and home are the Lucia Motion Library at motion.hellolucia.ai (LUCI-170). Lucia Library is this documentation; Lucia Motion Library is the motion catalogue. The names do not collide (founder, 2026-08-30). Seed inventory named on the record: the Lucia Orbit loader, the motion runtime conventions, the stroke-draw check, and the saved-card pixel-wave fill (LUCI-170). Animated icons joined the library on 2026-09-04 (LUCI-191, completed), installed per repository and per icon, every one honouring reduced motion. As of 2026-09-10 the gallery is published as an access-walled internal site, not a public page, so this Library links nothing and reproduces no recipe. When a motion is needed, the rule is the founder’s: adopt what the library holds, add what is new, never recreate.

​
8. Tips and guides

Founder, 2026-08-22 (FILD-100): the Apple TipKit pattern is the tip design for tooltips, guides, and coach marks across the Fieldwork app “and probably the entire platform”. Tips anchor to first real moments, never decorate a clean home on launch, dismiss with a close mark or a word, remember that they were seen, and never slow capture. The design laws of section 3 bind them in full. The six Fieldwork tip surfaces are documented on the Fieldwork product pages.

​
Before you design or add a surface

  1. Read LUCI-249 for the dress and LUCI-262 for the Masthead before touching any page top.
  2. Write every owner word by the rules in Voice and Tone.
  3. Plain i. No left bars. No pills. Corners 3 to 5px. Dots stay round.
  4. Show the founder a rendered top beside Bookings before committing.
  5. Motion: adopt from the Lucia Motion Library; name where it is used.

​
See also