ZAO造

Design notes

Quiet instrument is the chosen direction for Su. Read its intent, component decisions, and what to judge as the style develops.

design.md

Status: Current local Su study, selected on Oct 4, 2026. Trial palette and finish values remain local; Button, Card, Menu, and Tabs follow their individual shared approvals. The detailed working guide is styleguide.md in this folder.

Direction update, Oct 6, 2026: Quiet construction is the current design direction across ZAO, not a third finish or a rename of Quiet instrument. It explores the boundary of 2D clarity and 3D presence through clean, measured, coherent physical construction and a quiet responsive feeling. Yingzao Fashi informs proportion, parts, assembly, and finish. The Oct 7 scope focuses on Su in light and dark; Yu is deferred as a possible phase 2. A designed resting state may already have depth.

Care for every detail; keep the number of details small. Give visual form, interaction, and craft equal attention. Use a small, coherent set of details, each with a clear purpose. Refine the details already present before adding more.

Theme comes first. Yankun defines individual interactions one by one. Hairline's source informs the feeling and the process of testing and refining rules, not artwork rules or timings to copy. Usability benefits remain hypotheses that need evidence. The study ID and finish timing remain unchanged; palette refinements are recorded below, and the Button approval below replaces its earlier press movement.

Clarity comes first: typography, hierarchy, alignment, and content stay easy to read and use. Feedback stays quiet and connected to the person's action. Depth, material, and motion earn their place through their character and contribution to use; judge them in context before claiming better understanding or control.

Su's light and dark modes share proportions, component anatomy, and interaction meaning. For people and agents, fewer choices, better defaults, shared parts, semantic tokens, and clear guidance support consistent application. Readable states, keyboard access, and reduced motion remain part of the construction.

Button approval and refinement, Oct 6: Follow Yankun's Figma reference for the square face, 14px Geist at weight 500, 18px line box, and default 16px horizontal / 8px vertical padding (34px overall height). Use ZAO semantic colors, which this local study supplies. Connect face, side, and stationary base with a contact edge at rest. Hover retains the 2px upward-and-right lift and reveals the connected side edge, without a stronger hover border or blur. Press seats the face onto its base along that same axis; release returns it to the hovered or resting pose. The native hit area, neighboring layout, and outside keyboard focus outline stay fixed. Reuse the existing finish duration; disabled and reduced-motion protections remain intact. Press feedback acknowledges input, rather than claiming the action succeeded. Other component interactions remain open.

Button simplification, Oct 7: Use one face, one continuous joined side, and one fixed base, replacing the three visible offset shadow copies. Keep the approved geometry, 2px upward-and-right lift, press axis, and existing finish duration. The native hit area, focus outline, and neighboring layout remain stationary; variants, disabled behavior, and reduced-motion feedback stay intact.

Card approval, Oct 6: Use a static, grounded frame and contact edge in ZAO semantic colors around one content plane. Let the title lead, with subordinate metadata and optional open, unfilled data regions. Put explicit Button actions in a bottom row; the core Card stays passive, with no hover motion. Consolidate the storage specimen into one accurate, fully visible 68% chart derived from its specimen data. Keep existing fen proportions and type roles. Other component interactions remain open.

Card data refinement, Oct 6: Split's storage gauge uses 100 fine graduated radial marks, restrained concentric inner rings, and a single 68% readout. One storage value determines the readout and the 68 active marks. Stacked's stats use open ruled columns instead of a nested filled panel. Both data regions remain unfilled within the Card's content plane, using semantic colors without an invented waveform, motion, or glow.

Card layout compositions, Oct 6: Explore the same passive construction through four docs previews chosen with Layout tabs. Each selected preview appears at exact card widths of 640px and 480px together, labeled and stacked vertically. Split keeps the storage record and complete chart, with content/data side by side at 640px and stacked at 480px based on container width; Stacked suits a vertical reading sequence with bottom actions; Compact suits repeated workspace summaries with one small action; Media introduces a schematic illustration before the content and actions when it helps explain the record. Each sample keeps its width in a focusable horizontal scroll region on narrow docs views; the overall page and selectors fit the viewport. Layout changes composition; the Quiet instrument finish remains consistent across Su light and dark. The fixed comparison widths do not define published Card structure or tokens, and these previews add no Card variant API or hover motion.

Menu approval and Pocket reveal, Oct 6: Use a secondary Button trigger at shared 28px, 34px, and 40px sizes, with a clear open state. One floating frame anchors to the trigger, with a fine semantic border and crisp contact edge. A decorative moving front lip travels from the trigger-adjacent joint with the clipped reveal, becomes the far frame edge when open, and withdraws on close. Its direction follows actual collision placement. The full-size popup, labels, and selection targets stay stationary, without row stagger; current row emphasis stays steady through closing. Reuse existing duration-base for opening and duration-fast for closing, 160ms / 80ms in this study; reduced motion shows the completed frame immediately. Keep approved semantic row emphasis, meaningful separators, readable disabled items, and Base UI keyboard navigation, dismissal, focus behavior, and collision flip/shift. Su light and dark share structure and interaction meaning; material-overlay supplies the floating material. Further Menu row interactions and other component interactions remain open.

Table implementation and monochrome refinement, Oct 6: Refine the requested grounded ledger from the Button/Card/Menu review and Hairline's process. One square perimeter and contact edge surround an open canvas; fine horizontal rules and px-3 py-2 cell padding organize the records. The primary column receives the available width, supporting columns stay compact, IDs use monospace, and numeric readings align with tabular figures. Static and sortable headings share type-label; reserved indicator space keeps their geometry steady. Statuses use plain foreground text, checkboxes use the foreground, and selected rows use neutral bg-active. Metadata gains default foreground on emphasized rows. A compact secondary toolbar and concise selected count keep the specimen focused on its records. Native table parts, labeled controls, detailed live announcements, and a named scroll region retain reading and keyboard access on narrow views. Hairline informs economy and deliberate assembly; its figure geometry and motion remain references. Existing ZAO values supply the treatment. This requested refinement remains under review, with usability benefits to judge in use.

Requested field family working study, Oct 7: TextField, Combobox, and Select share 28px / 34px / 40px field heights, using the existing structural sizing without changing the general 32px control token. Quiet instrument gives them square stationary enclosures, recessed semantic fills, and a stronger perimeter on enabled hover and focus. Keyboard focus keeps an outside outline around the entire field, including Combobox's auxiliary actions; invalid edges stay distinct. Combobox reserves clear-action space. Both choice panels study Menu's Pocket reveal with a fixed frame, inner scrolling viewport, collision-aware front lip, existing opening/closing durations, and stationary wrapping option labels. A checkmark identifies the committed value while row emphasis identifies navigation; closing retains the last highlighted row's paint. Reduced motion completes the frame immediately. The shared mixed form and size comparisons use the real components on all three docs pages. Geometry, material, and reveal remain local study treatments; public props remain unchanged, and no finish values are promoted. Judge visual coherence, understanding, focus visibility, selection, narrow layouts, and repeated use before adopting the study as a default.

Light field availability refinement, Oct 7: The previous grey fill made enabled fields resemble disabled controls. Enabled light-mode TextField, Combobox, and Select now use the published semantic canvas as their clear value plane, with a fine border-default perimeter at rest. Disabled fields retain the grey bg-sunken plane, quieter border, and disabled text. Error fields share the clear plane while keeping their semantic error edge. Hover and focus strengthen the perimeter without changing fill or geometry. Dark mode, option panels, and the surrounding light canvas retain their current treatments. This remains a local working-study refinement, with no token or component API changes.

Requested data visualization study, Oct 7: The working guideline starts with Card's existing 68% ring. The docs specimen retains its graduated ticks and inner references; pointer or native region controls inspect used/available capacity without moving quantitative marks or the Card. The inner reference traces the inspected region. The later Oct 7 refinement removes the Illustrative data section and its simulation and particle controls. Ticks, values, and available capacity share the fixed 68% reading. Motion reuses the existing finish duration and easing, with immediate reduced-motion feedback. This is the requested local chart study; no waveform loops, published chart APIs, dependencies, or tokens are introduced. Further chart interactions remain open.

Approved Tabs, Oct 7: Primary views use the refined ruler rail: one fine guide and a slightly stronger selection line share their centerline, with fine graduations, centered registration ticks, and small end stops. Hover or keyboard focus extends the target tick without moving selection; press compresses the selected line around the same centerline. Secondary views use a square recessed track with one sliding face, a contact edge, and press seating, with no repeated underline. Labels, native targets, focus outlines, and layout stay stationary. Preserve Base UI selection, horizontal and vertical keyboard navigation, disabled behavior, nested state, scrolling, and reduced motion. Reuse semantic colors and existing finish durations; this approval is specific to Tabs and introduces no token changes.

Approved Switch, Oct 7: Use one square stationary housing, a recessed channel, and one connected sliding face. Position and semantic fill identify off and on. Hover changes face emphasis without moving it; press seats the face, and activation travels directly to the opposite endpoint without overshoot. Rapid toggling reverses from the current position. Use a 40px by 24px housing with a 16px square face. Keep the native target, outside focus outline, and neighboring layout fixed during interaction. Associate a clickable visible setting label whose wording stays stable. Base UI owns activation, controlled and uncontrolled state, and form behavior. Preserve disabled and read-only states, keyboard, touch cancellation, and RTL. Reduced motion shows the destination immediately and retains press feedback through fill. Reuse semantic colors and existing finish durations in Su light and dark; this approval is specific to Switch and adds no tokens or public API.

Current study idea

Approved Composer and Conversation implementation, Oct 7: Use the working-transcript direction. Composer groups included context and local attachments, a clear multiline writing plane, and existing labeled action Buttons inside one stationary square frame. A fine semantic rule joins the action row; body, label, and caption roles and fen spacing establish hierarchy. Enter adds a line and Cmd/Ctrl+Enter sends; the native textarea grows from three to eight lines without animation. The next draft stays editable while responding. File previews remain local and temporary; uploads, request acceptance, draft clearing, and response lifecycle belong to the host. Failed requests retain their draft and explain how to retry.

Conversation keeps a shared left reading axis, explicit authorship, restrained user surfaces, and open assistant prose. Rich results reuse the existing Card and Table construction. Native chronological lists sit inside a named, keyboard-focusable viewport. Follow content while at the bottom, preserve scroll-back, and expose Latest response without stealing focus. Separate polite feedback announces lifecycle transitions rather than tokens; stopped and failed responses preserve readable partial content. This approval covers these two families and their local docs simulations. It adds no global interactions, new motion values, runtime dependencies, or published token changes. Comfort during long reading, context understanding, and recovery remain usability hypotheses to judge in use.

Requested compact assistant refinement, Oct 7: The first version felt unfinished and consumed too much space for an assistant inside an application. Replace its stacked form bands with one writing tray: a one-line resting draft with at least a 24px writing target that grows to eight lines, a visually hidden native label, concise inline context, wrapping file tiles with 32px previews, and a 28px IconButton toolbar. Preserve the full accessible names, hover and focus tooltips, associated keyboard guidance, and all request safeguards. Keep the action row free of a visible shortcut hint, instructional row, or divider. Reuse Card's stationary contact edge and the semantic perimeter to make the enclosure feel complete without adding motion or tokens.

The three design lenses converge here: product design prioritizes a smaller default footprint and fast repeated writing; craft prioritizes a coherent silhouette, aligned insets, and clear edge hierarchy; Rams's principles remove duplicate labels and instructional chrome. Icon actions trade some immediate discoverability for density, so their labels and keyboard tooltips remain part of the control. Hairline's design process informs reducing competing interior edges and judging the composed resting state; its geometry and timings are not copied. Conversation gives short requests only the surface they need, uses deliberate turn spacing and subordinate metadata, and leaves assistant prose open. The docs show one embedded assistant panel with a docked composer and working copy actions; local simulation controls sit outside that surface. Judge writing comfort, file-name access, authorship, and recovery at desktop and narrow application widths before claiming a usability improvement.

Requested Composer focus and context refinement, Oct 7: A pointer click places the caret without drawing a second black enclosure around the writing area. Keyboard entry keeps the existing semantic focus outline. Supplied context uses square surface chips with fine semantic borders and named removal IconButtons; the host owns removal from the next request. Removing a chip returns focus to the draft, retains the pointer or keyboard focus treatment, and preserves the draft, files, and transcript. The empty context region disappears. This refinement adds no global focus changes, tokens, or motion values.

Requested Composer attachment alignment, Oct 7: Align the visible plus sign with the shared left edge of context chips and draft text. Offset the complete Attach files control using its existing size and icon tokens; keep its 28px target, approved construction, tooltip, and stationary focus outline intact.

Requested Composer shortcut hint removal, Oct 7: Remove the visible Ctrl / Cmd + Enter hint from the action row. Keep the keyboard shortcut and the input's accessible guidance; Attach files and Send or Stop remain the visible controls.

Approved raised Composer tray refinement, Oct 7: Keep the compact canvas-colored writing face and square enclosure. A border-subtle perimeter and one joined lower contact edge establish a clearer hierarchy at rest. Composer owns this construction: the contact retains the existing left/down offset of half a half-fen, with no blur or spread, using border-default at rest and border-strong immediately while the textarea has focus. Toolbar and chip focus keep their own control treatment; disabled Composer uses a subtle contact edge. Filled bg-sunken context chips have readable default text, transparent borders that retain their dimensions, and optional host-supplied decorative icons. The docs identify workspace and snapshot context with Folder and Database. The aligned plus, 28px action targets, clear pointer writing plane, keyboard outline, and native draft behavior remain intact. Work-state text belongs outside Composer; its icon-only controls retain their Send/Stop states, including busy semantics while stopping. This approval is specific to Composer and introduces no theme, published token, runtime dependency, or motion-value changes. Judge completeness, context recognition, and editing feedback in the real finishes and application widths before claiming a usability improvement.

Requested neutral Composer display, Oct 7: Present the standalone Composer as a general component with context, empty, disabled, and send-error states. Remove the assistant/workspace scene header, simulation switch, lifecycle captions, and accepted-request panel. Use generic draft and context examples; retain local Send/Stop behavior, attachment preparation, and failure/retry within the relevant state specimen. This is a docs presentation change; the reusable component's construction, public API, and host responsibilities remain unchanged.

Requested Composer plus spacing refinement, Oct 7: The supplied assistant references show a readable plus with room for its hover face below the draft. Use the existing 20px icon size for Attach only, while retaining its 28px native target and approved quiet IconButton construction. Align the visible plus drawing with the draft and context chips using that icon's geometry. A 16px horizontal tray inset gives the offset control more side clearance; retain 12px vertical padding and add one fen before the toolbar. The tray grows only 4px vertically. Square geometry, Send/Stop sizes, stationary targets and keyboard outlines, tooltips, draft behavior, and semantic finish values remain intact. This is a component refinement; the reference's model selectors and rounded enclosure are outside this request.

Make each control feel like a dependable instrument. The visual hierarchy comes from recessed inputs, precise keys, and open readings, with immediate control feedback. The monitoring references inform the material and feedback; the UI uses actual component data rather than invented telemetry.

Palette update, 2026-10-06: The base palette is now achromatic in light and dark. Grayscale equivalents preserve the previous luminance relationships while removing the green tint. Semantic success and error colors still identify outcomes. Hairline's figures add a refinement cue: open space, fine linework, and clear contrast between the subject and its supporting detail.

Requested light background refinement, Oct 7: Remove the separate grey backing from the shared light component previews by inheriting ZAO's published semantic page canvas. The light study no longer supplies a local --canvas or --zao-color-bg-canvas override. Dark retains its local canvas mapping. Surface, well, hover, selection, and floating material fills keep their existing roles; this request is confined to the light preview backing, with no token promotion.

Current component observations

Requested Progress refinement, Oct 7: The data visualization guideline informs a fixed square recessed track and one advancing face. A perimeter painted over the track leaves the quantitative span intact; the contact edge and face end remain inside the measured geometry. The label and formatted value sit outside. Unknown completion has an interrupted full-span reference and an “In progress” reading, with no occupied fraction or idle motion. The first reading appears immediately; actual value changes use existing duration-base and easing-standard, while reduced motion shows the destination immediately. Zero, full, fractional, and custom-range readings share Base UI's calculation and semantics; invalid ranges show unknown completion. The docs identify illustrative inputs and give the known-unit sample its total and remaining amount. This component request introduces no tokens, dependencies, or public props. Judge reading accuracy and construction clarity across finishes and narrow layouts before claiming a usability benefit.

Button, Card, Menu, Tabs, and Switch follow their individual approvals above. The other observations describe the existing study, not prescriptions for new interactions or system-wide motion commitments.

  • Button: The shared construction has one square face, one continuous joined side, and one fixed base with a contact edge at rest, the approved hover lift, and same-axis contact on press. Primary has the highest contrast and secondary has an explicit frame; both retain their resting fill and border on hover. Quiet gains a surface on hover. Hover does not add a stronger border or blur. Release returns the face to hover or rest. The face uses this study's existing 80 ms finish timing; the earlier movement of the native shell stays removed.

  • Field family: TextField, Combobox, and Select use the requested square recessed enclosure with one perimeter. Enabled hover and focus strengthen the border without moving the field. The outside keyboard outline surrounds the whole control; invalid edges stay distinct. Choice panels use the local Pocket study, stationary wrapping rows, and a fixed decorative lip around a separately scrolling viewport.

  • Card: A passive reading surface with a static frame and contact edge. Its title leads the record; open, unfilled data regions hold Split's complete storage gauge or Stacked's ruled stat columns. A bottom row exposes explicit Button actions with their own interaction and focus behavior.

  • Menu: A secondary Button opens one anchored floating frame through Pocket reveal. A decorative moving lip completes the far frame edge while the popup, labels, and targets stay stationary. Closing retains current row emphasis until the panel disappears. Meaningful divisions and readable disabled labels support the choices.

  • Table: One square grounded frame contains an open monochrome reading plane with fine rules and shared fen padding. A flexible primary column, compact supporting columns, monospace IDs, matching heading roles, and aligned tabular numbers define the hierarchy. Statuses stay plain; neutral selection follows record IDs through sorting. A compact secondary toolbar exposes explicit actions, and the docs comparison reports the selected records and their actual item total. This is the requested refinement under review.

  • Switch: One square fixed housing holds a connected sliding face at two endpoints. Semantic fill and position carry state; hover changes face emphasis, press seats it, and activation travels directly without overshoot. The clickable label remains stable. Reduced motion retains fill feedback and immediate endpoint changes; disabled states retain their readable endpoint. Travel uses existing duration-base; press and fill use duration-fast. Judge immediate state recognition, rapid reversal, and comfortable label activation in the settings list before claiming a usability benefit.

Current study constraints within shared ZAO structure

Geist remains the text and display face in this study. Geist Mono is used only for the record ID. ZAO owns all type roles, spacing, and control heights, including Button's reference-defined type role and the field family's approved 34px default height. The trial palette has light and dark versions; both retain readable labels, disabled states, and semantic error and success cues. This study has no glass or ambient animation. Reduced motion keeps Button's face stationary and removes transitions while preserving semantic hover/press fill feedback; Menu displays its completed frame immediately. Disabled Buttons retain native disabled behavior and do not move.

What to judge

This study aims for an operational character. Whether the recessed inputs and grounded card frame remain comfortable during long use is still an open question. Judge whether the title, complete chart, and bottom actions read clearly in both modes, narrow layouts, and cards without a data region. Compare the four layouts by their content needs, keeping the construction and finish consistent. For Menu, judge whether the trigger's open state and the panel's attachment stay clear during pointer and keyboard use, dismissal, and collision repositioning. Other component interactions remain pending Yankun's definition.