# Plavon consistency library Every piece a Plavon build is made of, in one way only. Use these pieces and nothing else; a screen that needs a new one adds it to the library first. House rules: buttons, menu items and tabs in Title Case; labels and sentences in sentence case; no em-dashes in text a person reads; colours through the tokens (consistency/tokens.css); anything that scrolls fades at its edges (consistency/scroll.css); a person without a photo is their gradient, never initials. A client's logo is drawn as itself, full size: their mark (or their whole lockup) at its own shape, then their name beside it, on the ground it sits on; never inside a tile, a coloured or black square, a rounded box or a circle, and never their initials in a box. Motion is one curve, the glide (`ease-glide`, no overshoot, nothing bounces), with the durations in consistency/tokens.css; a box whose content changes (a list filtered, a row added, a message shown) gets `useGlide` (hooks/use-glide.ts) so it follows its content with its top edge fixed, rows sliding, leaving blurred and arriving sharpening; anything floating is anchored by its top, never its bottom. ## Pieces ### Foundations The tokens everything reads: colour, type, corners, shadows and motion. - Colours (`colours`): The palette: one near-black ink in five softer steps for text, warm off-white grounds, fills of the ink at a few percent, and four state colours. - Type (`type`): The type scale: Inter in seven steps, from a 44px display to an 11.5px caption, with tabular figures for numbers. - Corners and shadows (`surfaces`): The corners and shadows: 10px menu rows, 11px keys and small chips (rounded-md), 14px fields and menus, 20px cards, 28px stages and dialogs, pills for what is pressed, and three shadows (rest, lift, float). - Motion (`motion`): One curve, the glide (--ease-glide, no overshoot), and a few durations, applied to every piece by its data-slot in consistency/motion.css; a box whose content changes follows it with useGlide. ### Buttons Everything pressed: buttons, toggles and the bars they sit in. - Button (`button`): A pill-shaped button for an action, in seven variants (default, secondary, outline, ghost, destructive, destructive-outline, link) and five sizes, with a loading state. - Icon button (`icon-button`): A Button holding only a glyph, round, in five sizes (icon-xs to icon-xl); the glyph grows a little on hover and sinks on press. - Button group (`button-group`): Buttons side by side as one control: attached into one pill sharing a hairline, or split a hair apart for an action and its options. - Toggle (`toggle`): A button that stays down: a quiet pill that fills while on, for one on or off choice made in place. - Toggle group (`toggle-group`): Toggles in a row on one track, letting several be on at once (multiple) or one at a time. - Segmented control (`segmented-control`): A few labelled options on a pill track, with a white thumb that glides to the one chosen. ### Inputs Everything typed into, with its label, hint and error. - Input (`input`): A single-line text field with a soft edge that darkens and takes a grey halo on focus, in three heights (sm, default, lg). - Search field (`search`): A pill-shaped search box with the glass, the words and a ⌘ K hint while empty, and a clear button once something is typed; Escape clears it. - Text area (`textarea`): A multi-line text field that grows with what is typed, from a 96px minimum, with the same edge and focus as the input. - Input group (`input-group`): An input (or text area) with addons inside its edge: an icon, a fixed text such as https:// or .ca, a unit, or a small button. - Number field (`number-field`): A number with minus and plus buttons on either side, centred tabular figures, and min, max and step limits. - One-time code (`otp-field`): A row of cells, one per digit, for a one-time code sent by email or text, with paste filling every cell and an optional separator. - Field, label and form (`field`): The frame around one form control: Field ties a FieldLabel, a FieldDescription and a FieldError to it, and Fieldset groups fields under a legend. ### Checkboxes, switches and sliders Every on and off, alone and in groups, and a value along a track. - Checkbox (`checkbox`): A small box that is ticked or not, alone or beside its words, with a mixed state for a box standing for several. - Checkbox group (`checkbox-group`): Several checkboxes answering one question together, holding the ticked ones as one list of values. - Radio group (`radio-group`): A short list of options where exactly one is picked, each a round button beside its words. - Switch (`switch`): An on and off control that takes effect the moment it is flipped. - Slider (`slider`): A value, or a range between two values, picked by dragging a thumb along a track. ### Dropdowns and selects Everything that opens a list: selects, comboboxes, menus, the team selector, the command bar. - Select (`select`): A field that opens a list of fixed options and holds the one picked. - Combobox (`combobox`): A field you type into to narrow a list and pick one of its items (or several), never free text. - Autocomplete (`autocomplete`): A text field that suggests values as you type and keeps whatever is typed, suggestion or not. - Team selector (`team-selector`): A pill showing the current team or company that opens a menu to switch to another, create one or open its settings. - Dropdown menu (`menu`): A button that opens a list of actions, with shortcuts, submenus, checks and a destructive end. - Context menu (`context-menu`): A menu of actions that opens at the pointer on a right click, or a long press on a touch screen, over an area. - Command bar (`command`): The ⌘K bar: a dialog with one search field that finds pages, records and actions in groups and runs the one picked. ### Dates A month to pick from, alone or in a field, and a period for a report. - Calendar (`calendar`): A month of days to pick one day, or a range of days, from, drawn in the page. - Date picker (`date-picker`): A field-like button that opens a calendar in a popover and shows the picked day in words. - Date range picker (`date-range-picker`): A pill that says a period in words and opens named periods, "the last N", two typed ends and two months to pick any range from. ### Dialogs, sheets and popovers What opens over the page, how it opens and how it closes. - Dialog (`dialog`): A card that opens over a dimmed page and holds one short task: a header, a panel that scrolls, and a footer of actions. - Alert dialog and confirm (`alert-dialog`): A dialog that asks one question before something happens; `ConfirmDialog` is its ready form for a destructive action, where the thing's name must be typed first. - Sheet (`sheet`): A panel that slides in from an edge of the window over a dimmed page, with a header, a scrolling panel and a footer. - Drawer (`drawer`): A panel that rises from the bottom (or comes in from any edge), follows the finger and closes with a swipe, the way a phone's sheets do. - Popover (`popover`): A small floating card anchored to a button, with no backdrop, that closes on a click outside or on Escape. - Tooltip (`tooltip`): A small dark label that appears beside a control on hover or keyboard focus, after a short wait. - Term (`term`): A word with a dotted underline whose meaning shows in a tooltip on hover or focus. - Preview card (`preview-card`): A card that opens when the pointer rests on a link, previewing what the link leads to. ### Navigation How a person moves through a tool. - Sidebar (`sidebar`): The tool's main navigation down the left side: the team selector at its head, each place a `NavItem` row, the current one white and lifted off the warm ground. - Tabs (`tabs`): A row of tabs that switches between panels of one page, drawn as pills with a sliding white thumb or as an underline. - Breadcrumb (`breadcrumb`): The path from a list down to the record being shown, each level a link and the last one the current page. - Pagination (`pagination`): Previous and Next with page numbers between them, for moving through a long list one page at a time. - Toolbar (`toolbar`): A floating pill that groups related controls, such as formatting buttons, into one stop for Tab with the arrow keys moving between them. - Accordion (`accordion`): A stack of headings that each open their panel below, one at a time unless `multiple` is set. - Collapsible (`collapsible`): One trigger that shows or hides one panel below it, its height animated. ### Badges, avatars and cards What content sits on and what labels it. - Badge (`badge`): A small pill that labels something with a word or a number: a status, a count or a tag. - Avatar (`avatar`): A person's round picture, or their own colour gradient when there is no photo. - Card (`card`): A white surface with rounded corners and a soft shadow that holds one subject. - Frame (`frame`): A grey tray that holds one or more white panels under a quiet heading. - Keyboard key (`kbd`): A keycap that shows a key or a keyboard shortcut. - Separator (`separator`): A one-pixel line that divides content, across or upright. - Scroll area (`scroll-area`): A box that scrolls its content behind a thin scrollbar and fades the edge that has more to show. ### Tables and figures Rows of data and how far along something is. - Table (`table`): Rows and columns of records under a header row, scrolling sideways with a fade when wider than its box. - Progress (`progress`): A bar that fills as a task moves toward done. - Meter (`meter`): A bar that shows where a measure sits within its range. ### Charts Numbers drawn: over time, in parts, ranked, toward a goal, by hour. Every one answers the pointer and glides to new data. - Stat (`stat`): One figure that matters: its label, its value, how it moved against a named period, and an optional sparkline under it. - Sparkline (`sparkline`): A trend drawn as a small line beside or under a figure, with no axis: the past in grey, the latest stretch and its point in blue. - Area chart (`area-chart`): A value over time: one 2px line per series, the first washed underneath, the period before as a quiet dashed line, a crosshair that finds the nearest date. - Bar chart (`bar-chart`): Amounts as columns from one baseline: one series, several side by side, or stacked as the parts of each period. - Bar list (`bar-list`): A ranking: one row per name, longest first, a thin bar of its share of the first, the value in text, its share of the whole on hover. - Donut chart (`donut-chart`): The parts of one whole as a ring, five at most (more fold into Other), the total in the middle and a legend with each value and share. - Progress ring (`progress-ring`): How far toward a goal: a ring whose track is a lighter blue, filled in blue from the top, the share in the middle. - Heatmap (`heatmap`): When things happen: a grid of cells, one blue from light to dark for how many, the empty cell grey, the scale under it. ### Feedback and empty states What tells a person something happened, is loading, or that nothing is here yet. - Toast (`toast`): A short message that slides in at the corner to say something just happened, then goes away on its own. - Alert (`alert`): A block in the page, tinted by its meaning, that states a condition and what to do about it. - Empty state (`empty`): A centred message that says a place has nothing in it yet and offers the way to fill it. - Skeleton (`skeleton`): A grey shape with a soft shimmer that stands where content will appear while it loads. - Spinner (`spinner`): A small spinning circle that says something is working. ## Colours (`colours`) Section: Foundations. File: `consistency/tokens.css`. Page: /consistency/colours The palette: one near-black ink in five softer steps for text, warm off-white grounds, fills of the ink at a few percent, and four state colours. **Use case.** Read this before colouring anything a layout draws itself. Text takes the ink steps by importance (a client's name in the ink, body text in ink 2, a column's label in ink 4), grounds take the page white or the warm surfaces (a side column, a well), and a quiet fill or hairline is the ink at a few percent rather than a grey of its own. Success, warning, destructive and info are kept for states such as paid, due soon, overdue and a note to read. What is on (a tick, a filled radio, a switch turned on, how far a progress bar has come) is the blue `selected`, never the ink, which stays the one button that matters. **Use it when:** - Colouring text by importance: the ink, then ink 2 to ink 5 - Choosing the ground of a page, a well or a side column - A quiet fill or hairline that has to read on white - Showing a state such as paid, late or failed **Use something else when:** - A status word on a row (Paid, Overdue): use Badge (`badge`) - A tinted message about the page or a form: use Alert (`alert`) - The corner and shadow of a block: use Corners and shadows (`surfaces`) **Rules:** - Colours come from the tokens only (consistency/tokens.css), never a hex in a piece or a layout, so a client's brand is that one file. - The ink itself is text-foreground or bg-primary; its steps are text-ink-2 to text-ink-5 (there is no text-ink utility). - A fill or an edge is the ink at a few percent (bg-secondary, border-border, bg-[rgb(var(--ink-rgb)/0.09)]), never a grey of its own. - On a white ground, text in a state colour uses its -foreground token (text-destructive-foreground); the plain token is for a fill (bg-destructive). - The chrome-* tokens belong to the showcase's frame and are never used in a client's tool. **Import:** ```tsx /* the tokens load once, in app/globals.css */ @import "../consistency/tokens.css"; ``` **Usage:** ```tsx

Balance due

$1,204.60

Invoice 2041 for Atelier Nord.

Overdue by 4 days

``` ## Type (`type`) Section: Foundations. File: `consistency/tokens.css`. Page: /consistency/type The type scale: Inter in seven steps, from a 44px display to an 11.5px caption, with tabular figures for numbers. **Use case.** Use it to size any text a layout writes around the pieces: a page title at 28px, a card's heading at 17px, a paragraph at 15px in ink 2, a row or a button's words at 13px, a timestamp or caption at 11.5px in ink 4. Every amount, count and date that lines up in a column (an invoice total, a quantity, an order number) takes tabular figures. The pieces already set their own type; this is for what the layout adds. **Use it when:** - A page title, a card heading or a section heading - Body text, a hint or a caption a layout writes itself - A figure that has to line up: an amount, a count, a date **Use something else when:** - The label, hint and error of a form control: use Field, label and form (`field`) - A short status word on a row: use Badge (`badge`) - A keyboard shortcut written as keys: use Keyboard key (`kbd`) **Rules:** - Weights are 400 and 500 (font-medium): every step of the scale is one or the other, never bold. - Numbers that are compared or stacked carry tabular-nums. - Labels, headings and sentences in sentence case; Title Case only on buttons, menu items and tabs. - No em-dashes in text a person reads: use a colon, a comma or parentheses. - Inter (font-sans) throughout; font-mono is for code only. **Import:** ```tsx /* Inter is font-sans, set on html in app/globals.css */ ``` **Usage:** ```tsx

Invoices

Waiting to be paid

Three invoices are past their due date.

Atelier Nord $1,204.60 Sent October 2 ``` ## Corners and shadows (`surfaces`) Section: Foundations. File: `consistency/tokens.css`. Page: /consistency/surfaces The corners and shadows: 10px menu rows, 11px keys and small chips (rounded-md), 14px fields and menus, 20px cards, 28px stages and dialogs, pills for what is pressed, and three shadows (rest, lift, float). **Use case.** Use it whenever a layout draws a shape of its own: a panel of order details is a 20px block resting on --shadow-rest, a tile that rises under the pointer takes --shadow-lift, and anything floating over the page takes --shadow-float. Most of the time a piece (card, dialog, popover) already wears the right shape, and the layout should use the piece rather than redraw it. **Use it when:** - A layout block that needs a corner or a shadow of its own - Checking which radius belongs to which kind of thing - A tile that lifts when the pointer is over it **Use something else when:** - A block of content with a title and a body: use Card (`card`) - Several panels on one warm ground: use Frame (`frame`) - Something that floats over the page from a trigger: use Popover (`popover`) **Rules:** - Corners come from the ladder: rounded-[10px] for menu rows, rounded-[14px] for fields and menus (rounded-lg is 14px), rounded-[20px] for cards, rounded-[28px] for stages and dialogs, rounded-full for what is pressed. - Shadows come from the three tokens only: shadow-(--shadow-rest) on the page, shadow-(--shadow-lift) as it rises, shadow-(--shadow-float) for what floats over it. - A focusable element of a layout's own shows focus with focus-visible:shadow-(--focus-ring), as the button does. - A field being typed into shows --field-focus-border and --field-focus-halo, never a black outline. **Import:** ```tsx /* the radius and the shadows are tokens in consistency/tokens.css */ ``` **Usage:** ```tsx

Order 1048

Ready for pickup

Atelier Nord
A stage around the content
``` ## Motion (`motion`) Section: Foundations. File: `consistency/motion.css`. Page: /consistency/motion One curve, the glide (--ease-glide, no overshoot), and a few durations, applied to every piece by its data-slot in consistency/motion.css; a box whose content changes follows it with useGlide. **Use case.** The pieces already move: a button sinks to 0.96 on press, a check pops in, a switch knob and a tab's pill slide, menus grow in from their trigger, the command bar and the comboboxes glide to their new height as you type. Reach for this when a layout changes content of its own: a list filtered by a view, a row added to an order, a condition added to a filter, a message that appears in a card. Put useGlide on the box that holds the content and it follows every change, its top edge fixed, the rows sliding, leaving blurred and arriving sharpening. Take any other curve or duration from the tokens; nothing in the library bounces. **Use it when:** - A box whose content changes size: useGlide on the box, data-glide-item on its rows - Something that moves to a new place, such as a pill or a knob (ease-glide, --dur-slide or --dur-tick) - Something that appears in place (ease-glide, --dur-enter, from opacity 0 and a few pixels) - A press on something the layout draws itself (ease-press down in --dur-press, ease-glide back) **Use something else when:** - Something that opens over the page: its motion comes with the piece: use Dialog (`dialog`) - A panel that opens and shuts: its height is the piece's own: use Collapsible (`collapsible`) - Content that is still loading: use Skeleton (`skeleton`) - A short wait on an action: use Spinner (`spinner`) **Rules:** - One curve: ease-glide (cubic-bezier(0.32, 0.72, 0, 1)) for everything that moves, grows, shrinks or slides; ease-press only for the finger going down. Never a spring that overshoots, never ease-in, never linear except a progress that is time itself. - Durations are tokens: --dur-press 130ms, --dur-color 160ms, --dur-popup 160ms, --dur-tick 200ms, --dur-enter 240ms, --dur-slide 300ms, --dur-glide 360ms. A size or a position following content may take the full 360ms because nothing waits on it; anything a person waits on stays under 300ms. - A box that changes height keeps its top edge fixed and grows downward: anchor anything that floats by its top, never by its bottom, so a card that gains a row does not climb. - A box whose content changes gets useGlide (hooks/use-glide.ts, lib/glide.ts outside React) and overflow-hidden; its rows carry data-glide-item (library rows are found by their data-slot). Never animate height by hand with a fixed number. - A pill under a picked tab or segment slides to it (TabsList does it); never swap a fill from one tab to the other. - A piece gets its motion from its data-slot in consistency/motion.css: never add transition classes to a piece. - Name the exact properties (transition-[opacity,translate]), never transition-all; animate transform, opacity and filter, and height only through the glide. - Respect reduced motion: the glide applies the change at once; elsewhere motion-reduce:transition-none, or keep only the fade. - Hover effects only behind (hover: hover) and (pointer: fine); press feedback on :active. **Import:** ```tsx import { useGlide } from "@/hooks/use-glide" /* the curves are tokens.css, the pieces' motion is motion.css; both load once in app/globals.css */ ``` **Usage:** ```tsx {/* a list filtered by a view: the card follows it, top edge fixed */} const glide = useGlide()
    {rows.map((r) => (
  • {r.name}
    • ))}
{/* something appearing in place, on the glide */}
  • Order 1049, Atelier Nord
    • ``` ## Button (`button`) Section: Buttons. File: `components/ui/button.tsx`. Page: /consistency/button A pill-shaped button for an action, in seven variants (default, secondary, outline, ghost, destructive, destructive-outline, link) and five sizes, with a loading state. **Use case.** Use it for anything a person presses to make something happen: Save Changes at the foot of a client form, New Order on a page's title row, Send Invoice, Cancel in a dialog. The default (ink) variant is the one thing to do on the view; secondary, outline and ghost carry the rest; destructive marks an action that deletes or voids something. With render it can draw a link that looks like a button, such as View Invoice going to another page. **Use it when:** - The main action of a form or a page (the default variant) - Supporting actions beside it: Cancel, Export, Duplicate - An action that deletes or voids something (destructive, destructive-outline) - A link that should look like a button (render a Link) **Use something else when:** - The button shows only an icon: use Icon button (`icon-button`) - It stays pressed and shows an on or off state: use Toggle (`toggle`) - Several related buttons that read as one control: use Button group (`button-group`) - The action destroys data and needs a confirmation first: use Alert dialog and confirm (`alert-dialog`) **Rules:** - One default (ink) Button per view, the one thing to do; the rest are secondary, outline or ghost. - Labels in Title Case (Save Changes, Send Invoice). - A Button is type="button" by default: the submit button of a form must say type="submit". - Never set a size class on an icon inside a Button: each size sets its icons. - While its action runs, pass loading: the label hides, a spinner shows and the button is disabled at the same width. **Import:** ```tsx import Link from "next/link" import { PlusIcon } from "@/components/icons" import { Button } from "@/components/ui/button" ``` **Usage:** ```tsx
    ``` ## Icon button (`icon-button`) Section: Buttons. File: `components/ui/button.tsx`. Page: /consistency/icon-button A Button holding only a glyph, round, in five sizes (icon-xs to icon-xl); the glyph grows a little on hover and sinks on press. **Use case.** Use it for a compact action whose glyph is unmistakable: the trash on an order line, copy beside a portal link, a plus to add a line to a quote, the eye that shows a password inside a field. It saves room in tables, toolbars and title rows where a worded button would crowd. Anything a person could misread needs words, so it becomes a Button with a label. **Use it when:** - A row action in a table (delete, copy, edit) - A small action inside a field (show the password, clear) - Paging arrows beside a date or a record - A plus that adds a line or an item **Use something else when:** - The action is not obvious from the glyph alone: use Button (`button`) - The icon stays on or off (bold, favourite): use Toggle (`toggle`) - Several actions on a row, behind one button: use Dropdown menu (`menu`) - A name shown on hover for the glyph: use Tooltip (`tooltip`) **Rules:** - Always pass aria-label naming the action (Delete Line, Copy Link). - size is icon-xs, icon-sm, icon, icon-lg or icon-xl; sm and lg are for buttons with words. - Never set a size class on the glyph: each icon size sets it. - Inside a field (an input group) use the ghost variant at icon-xs or icon-sm. - On a touch screen the hit area grows to 44px by itself; do not pad it. **Import:** ```tsx import { CopyIcon, PlusIcon, TrashIcon } from "@/components/icons" import { Button } from "@/components/ui/button" ``` **Usage:** ```tsx ``` ## Button group (`button-group`) Section: Buttons. File: `components/ui/group.tsx`. Page: /consistency/button-group Buttons side by side as one control: attached into one pill sharing a hairline, or split a hair apart for an action and its options. **Use case.** Use it when buttons belong together and should read as one thing: Previous, Today and Next above a delivery schedule, or a split button where Send Invoice is the action and a chevron beside it opens the other ways to send. Attached (the default) joins them into one pill; attached={false} keeps each its own shape so a chevron reads centred. **Use it when:** - Paging through dates or records: previous, the current one, next - A split button: the main action and a chevron for its options - A short row of related actions that read as one control **Use something else when:** - One of several options stays selected (Day, Week, Month): use Segmented control (`segmented-control`) - Formatting switches that stay pressed: use Toggle group (`toggle-group`) - A whole bar of tools with separators: use Toolbar (`toolbar`) **Rules:** - The buttons of one group share a variant and a size. - An icon-only button in the group carries aria-label. - The Buttons are direct children of Group: its corners and shared hairline reach only direct children with data-slot="button". - attached={false} makes a split button; orientation="vertical" stacks the buttons. **Import:** ```tsx import { ChevronDownIcon, ChevronLeftIcon, ChevronRightIcon } from "@/components/icons" import { Button } from "@/components/ui/button" import { Group } from "@/components/ui/group" ``` **Usage:** ```tsx ``` ## Toggle (`toggle`) Section: Buttons. File: `components/ui/toggle.tsx`. Page: /consistency/toggle A button that stays down: a quiet pill that fills while on, for one on or off choice made in place. **Use case.** Use it for one switch that changes what is shown and is flipped often, right where the content is: Unread Only above a list of messages, Assigned to Me over the orders table, bold in a note's toolbar, a heart to mark a client as a favourite. It is a view or tool state, not a saved setting. **Use it when:** - A filter on the list on screen (Unread Only) - A single formatting switch (bold) - Marking something as a favourite in place **Use something else when:** - Several related switches side by side (bold, italic, underline): use Toggle group (`toggle-group`) - Exactly one of several options must be chosen: use Segmented control (`segmented-control`) - A saved setting that is on or off (email reminders): use Switch (`switch`) - An action that happens once when pressed: use Button (`button`) **Rules:** - An icon-only Toggle carries aria-label. - The label stays the same whether on or off; the fill says it is on. - Use pressed with onPressedChange when the state lives in your code, defaultPressed when it does not. - variant is default (a fill while on) or outline; size is sm, default or lg. - Labels in Title Case. **Import:** ```tsx import { BoldIcon } from "@/components/icons" import { Toggle } from "@/components/ui/toggle" ``` **Usage:** ```tsx const [unreadOnly, setUnreadOnly] = useState(false) Unread Only ``` ## Toggle group (`toggle-group`) Section: Buttons. File: `components/ui/toggle-group.tsx`. Page: /consistency/toggle-group Toggles in a row on one track, letting several be on at once (multiple) or one at a time. **Use case.** Use it for related tool switches that sit together: bold, italic and underline above a note, or grid and list icons that change how a product catalogue is laid out. With multiple any number can be on; without it, pressing one turns the others off, and pressing the one that is on leaves none. **Use it when:** - Formatting switches that can combine (multiple) - Icon switches for how a list is laid out (grid or list) - Several filters that can be on together **Use something else when:** - A labelled choice where exactly one is always picked: use Segmented control (`segmented-control`) - A single on or off switch: use Toggle (`toggle`) - Several options in a form that are saved: use Checkbox group (`checkbox-group`) **Rules:** - value and defaultValue are arrays of item values, even one at a time (defaultValue={["grid"]}). - Set variant and size on ToggleGroup: the items take them from the group. - Each icon-only ToggleGroupItem carries aria-label. - Without multiple, one at a time can end with none pressed; when that is not allowed, use a segmented control. **Import:** ```tsx import { BoldIcon, ItalicIcon, UnderlineIcon } from "@/components/icons" import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group" ``` **Usage:** ```tsx ``` ## Segmented control (`segmented-control`) Section: Buttons. File: `components/ui/segmented-control.tsx`. Page: /consistency/segmented-control A few labelled options on a pill track, with a white thumb that glides to the one chosen. **Use case.** Use it when exactly one of two to five short options is always chosen and the choice changes what is shown: Day, Week and Month over a schedule, 7D, 30D and 90D over a sales figure, Open, Paid and All above invoices. It is controlled: the value lives in state and the view reads it. **Use it when:** - Switching between views of the same content (Day, Week, Month) - A date range over a figure or a chart - A setting with two to five short options, one always chosen **Use something else when:** - Sections of a page that each have their own panel: use Tabs (`tabs`) - More options than fit on one line, or long labels: use Select (`select`) - Icon switches that may combine or may all be off: use Toggle group (`toggle-group`) - A choice in a form with a sentence for each option: use Radio group (`radio-group`) **Rules:** - It is controlled: pass value and onValueChange, and keep the value in state. - Always pass aria-label naming what is chosen (View, Range). - Option labels are short and in Title Case. - Each option is { value, label, disabled? }; size is sm, default or lg. - The thumb slides to the one picked on the glide in --dur-slide; never swap a fill from one option to the other. - It is exactly as tall as a Button of the same size (sm 30px, default 36px, lg 40px): in a row beside buttons, give both the same size, never a segmented control one size up. **Import:** ```tsx import { SegmentedControl } from "@/components/ui/segmented-control" ``` **Usage:** ```tsx const [view, setView] = useState<"day" | "week" | "month">("week") ``` ## Input (`input`) Section: Inputs. File: `components/ui/input.tsx`. Page: /consistency/input A single-line text field with a soft edge that darkens and takes a grey halo on focus, in three heights (sm, default, lg). **Use case.** Use it for one line of typed text in a form: a client's company name, an email, a phone number, an invoice number, a postal code. Put it in a Field with a FieldLabel so it is named and can show a hint or an error. The type attribute (email, tel, url, password) brings the right keyboard on a phone. **Use it when:** - A name, an email, a phone number or an address line - An identifier typed once: an invoice number, a postal code - Any one-line answer in a form **Use something else when:** - Several lines of text (notes, a message): use Text area (`textarea`) - Searching or filtering a list: use Search field (`search`) - An icon, a prefix, a unit or a button inside the field: use Input group (`input-group`) - A quantity stepped up and down: use Number field (`number-field`) **Rules:** - Every Input is named: a FieldLabel in the same Field, or aria-label. - Mark an error with aria-invalid (or invalid on its Field): the edge turns red. - Do not add a border, ring or outline: focus is the darker edge and grey halo from the tokens. - size is sm (34px), default (40px) or lg (48px). **Import:** ```tsx import { Field, FieldLabel } from "@/components/ui/field" import { Input } from "@/components/ui/input" ``` **Usage:** ```tsx Company name ``` ## Search field (`search`) Section: Inputs. File: `components/ui/search-field.tsx`. Page: /consistency/search A pill-shaped search box with the glass, the words and a ⌘ K hint while empty, and a clear button once something is typed; Escape clears it. **Use case.** Use it above a list or a table to narrow what is on screen: clients by name, orders by number, invoices by company. Large, it is a page's main search; small, it fits a toolbar above a table, level with the small buttons there. It is controlled: the value lives in state and filters the rows as it changes. **Use it when:** - Filtering a table or a list on the page (clients, orders) - A page's main search (size lg) - A search in a toolbar above a table (size sm) **Use something else when:** - Jumping to any record or action from anywhere, by keyboard: use Command bar (`command`) - Typing a value in a form with suggestions as you type: use Autocomplete (`autocomplete`) - Picking one item from a long list in a form: use Combobox (`combobox`) - A plain typed value in a form: use Input (`input`) **Rules:** - It is controlled: value and onValueChange are required. - Always pass aria-label (Search clients); the placeholder defaults to Search. - The ⌘ K hint is only drawn: wire the shortcut yourself, or pass shortcut={false}. - Escape and the clear button empty it; do not add a clear button of your own. - size is xs, sm, default, lg or xl, the buttons' own heights (26, 30, 36, 40, 48px): in a bar, give the search the size of the buttons beside it, never a height of its own. **Import:** ```tsx import { SearchField } from "@/components/ui/search-field" ``` **Usage:** ```tsx const [query, setQuery] = useState("") ``` ## Text area (`textarea`) Section: Inputs. File: `components/ui/textarea.tsx`. Page: /consistency/textarea A multi-line text field that grows with what is typed, from a 96px minimum, with the same edge and focus as the input. **Use case.** Use it for free text longer than a line: notes from a call with a client, a message to send, delivery instructions on an order, the description of the work on a quote. Put it in a Field with a FieldLabel, and a FieldDescription when there is a limit or a hint. **Use it when:** - Notes, a message, instructions or a description - Anything that may run past one line **Use something else when:** - One line of text: use Input (`input`) - A text box with a button or a row of actions attached (a composer): use Input group (`input-group`) **Rules:** - Every Textarea is named: a FieldLabel in the same Field, or aria-label. - It grows with its content (field-sizing-content): do not give it a fixed height. - Mark an error with aria-invalid (or invalid on its Field). - Do not add a border or ring: focus is the darker edge and grey halo. **Import:** ```tsx import { Field, FieldDescription, FieldLabel } from "@/components/ui/field" import { Textarea } from "@/components/ui/textarea" ``` **Usage:** ```tsx Notes