# nalet design system

> A dark, square, calm design system for admin consoles inside a portal shell. React components (v0.4.0), design tokens, and guidelines.
> Human guidelines: https://nalet.github.io/design-system/ · React implementation: https://nalet.github.io/design-system/react/ · Source: https://github.com/nalet/design-system

## principles (in priority order; the earlier wins a conflict) — https://nalet.github.io/design-system/foundations/principles/
1. The system does the work; people handle the exceptions. Automate routine work; a screen opens on what needs a person, then what is on its way; the full list is a drill-down.
2. The outcome is the status. One status per object, answering "can I use it yet?", the same in every app; internal steps are detail. Colour follows meaning; unknown says so.
3. People's words first, the system's detail one click away. No ids, file names or error codes as the message; keep them under details.
4. One platform, many apps. The shell owns sign-in, navigation, search, notifications, settings and the design system; one tile per app; setup found in settings, edited in the app; one top bar everywhere.
5. Calm and quick. One emphasized (primary) action per view, toolbar or dialog; no decoration; keyboard complete.
Baseline (never traded): WCAG 2.2 AA (text contrast >= 4.5:1, tested), named controls, visible focus, keyboard complete, works at phone width, docs state known gaps.

## voice — https://nalet.github.io/design-system/foundations/content-voice/
- Monospace (titles, headings, buttons, tabs, navigation, status chips, table headers, menu items, codes) is lowercase in every language; names and codes inside keep their case. The components lowercase by CSS, so wrap a name inside such a label in <KeepCase> (or class nc-keep-case): `find <KeepCase>German</KeepCase> for 4 selected`.
- The body face (descriptions, messages, toasts, dialog bodies, empty states, field labels and hints, docs prose) follows the language: sentence case, acronyms, German nouns capitalised.
- Messages: what is true, what it means, what to do. Buttons: a verb and its object ("grab 8 selected"), never "ok"/"submit".

## writing ui text — https://nalet.github.io/design-system/foundations/meaningful-text/
- Write from the facts of the running system (states, numbers, settings), not from the prompt: the prompt says what to build, not what the screen says.
- Keep the conversation off the screen: no request, ADR or plan wording, review notes or commit messages. Never mention a feature that isn't built.
- True on every installation: values that come from settings (languages, sources, limits, scope, where something is configured) are read from the configuration when the screen is shown, or left out. Never type one installation's setup into a sentence.
- Use the reader's words and speak to them ("you"); internal names, setting keys and error codes go under details.
- Leave out: repeats of what is visible; instructions the button beside them already gives (a failure says its reason, "Can't reach the server.", not "try again"); praise and promise words (seamless, effortless, smart, powerful, simply, successfully); hedges and padding (may, some, various, in order to, please note); decoration (emoji, exclamation marks, three-adjective lists, stacked dashes and colons).
- One number and one word per thing, across the whole screen.
- Before shipping, ask of every text: true right now? true on every installation? would anyone miss it? the reader's words? agrees with the rest of the screen? speaks to the reader? promises nothing unbuilt? reads well in a screenshot with real data?
- Find every text, including what the server writes (statuses, reasons, errors); search it for the request's wording and the project's internal words; list the texts you changed for review.

## tv focus (10-foot) — https://nalet.github.io/design-system/patterns/tv-focus/
- One focus style for every focusable item in a TV app, never a per-screen style: a 3 dp ring in --focus-ring (#00A4DC), the focused surface --surface-focus (#2A3142) behind rows, plain buttons and chips, growth 1.05 for cards, buttons and chips and 1.02 for rows, and text one step brighter (title --fg).
- Cards, buttons and chips: the ring outside with a 2 dp gap where the background shows. Rows: the ring inside the edge, no gap.
- The ring means focus only: "where you came from" is a 4 dp left-edge bar in --cloud-blue. 150 ms ease-out; none when animations are off. At least 12 dp between cards; everything focusable and all text inside the safe area (48 dp left and right, 27 dp top and bottom).
- dp = 1/960 of the screen width (2 CSS px on a 1920 × 1080 web screen). Screenshot tests of every kind, focused and at rest.

## identity — https://nalet.github.io/design-system/styles/brand/
Dark canvas only; the blue chevron (--cloud-blue) is the brand glyph and the colour of links and the primary action; square frames (border-radius 0); JetBrains Mono for display and labels, Inter for body; 4px spacing scale.

## components — guidance pages (React APIs: https://nalet.github.io/design-system/react/)
- button: Starts an action on this screen; one emphasized button marks the next step. https://nalet.github.io/design-system/components/button/
- icon button: An action shown as an icon only, with a name for screen readers. https://nalet.github.io/design-system/components/icon-button/
- action menu: Several actions behind one button, such as one menu per table row. https://nalet.github.io/design-system/components/action-menu/
- toolbar and selection toolbar: Actions above the content they act on; the selection toolbar acts on the selected rows. https://nalet.github.io/design-system/components/toolbar/
- input: One line of text. https://nalet.github.io/design-system/components/input/
- textarea: Several lines of text. https://nalet.github.io/design-system/components/textarea/
- select: One value picked from a short list. https://nalet.github.io/design-system/components/select/
- multi select: Several values of one filter, as checkboxes in a panel that opens. https://nalet.github.io/design-system/components/multi-select/
- checkbox: An option that is saved with a form, with a mixed state for “some of these”. https://nalet.github.io/design-system/components/checkbox/
- switch: A setting that takes effect at once. https://nalet.github.io/design-system/components/switch/
- field: A label, a hint and an error, joined to one control. https://nalet.github.io/design-system/components/field/
- filter bar: Search, filters, “clear all”, and the count of what is left. https://nalet.github.io/design-system/components/filter-bar/
- data table: A list people work through: they sort it, select rows, open groups and load more. https://nalet.github.io/design-system/components/data-table/
- table cells: A status with its reason, a date said both ways, an identifier. https://nalet.github.io/design-system/components/table-cells/
- table: A simple table for a short list that people only read. https://nalet.github.io/design-system/components/table/
- badge: A label, a count, a tag: not a status. https://nalet.github.io/design-system/components/badge/
- text: Text in one of the text styles. https://nalet.github.io/design-system/components/text/
- code: Code and commands, inside a sentence or as a block. https://nalet.github.io/design-system/components/code/
- kbd: A key to press. https://nalet.github.io/design-system/components/kbd/
- status: The state of one thing, with one of five meanings. https://nalet.github.io/design-system/components/status/
- banner: A message about the page or the list that stays for as long as it is true. https://nalet.github.io/design-system/components/banner/
- toast: A short confirmation of an action just taken. https://nalet.github.io/design-system/components/toast/
- empty state: What a list shows when it is empty, done, has no matches, failed or can't be known. https://nalet.github.io/design-system/components/empty-state/
- spinner: Something is loading, where nothing better shows it. https://nalet.github.io/design-system/components/spinner/
- box: Padding and a canvas background. https://nalet.github.io/design-system/components/box/
- stack: A row or a column with a gap from the space scale. https://nalet.github.io/design-system/components/stack/
- divider: A thin line between two parts of a page. https://nalet.github.io/design-system/components/divider/
- card: A framed panel with an optional header and footer. https://nalet.github.io/design-system/components/card/
- heading: A page or a section title. https://nalet.github.io/design-system/components/heading/
- modal: A decision that blocks the page until it is made. https://nalet.github.io/design-system/components/modal/
- tooltip: A short label for something that has no room for one. https://nalet.github.io/design-system/components/tooltip/
- tabs: Switch between the parts of one thing. https://nalet.github.io/design-system/components/tabs/
- filter tabs: Counts at the top of a list that also filter it. https://nalet.github.io/design-system/components/filter-tabs/
- tile: A square on the home page that opens an app, or shows a key figure. https://nalet.github.io/design-system/patterns/home-and-tiles/#the-tile
- tile group: A titled grid of tiles. https://nalet.github.io/design-system/patterns/home-and-tiles/#tile-groups

## patterns
- worklist: A page for working through what needs doing, with the one next step for each item. https://nalet.github.io/design-system/patterns/worklist/
- top bar: The bar across the top of every screen: where you are, the one search, what is new for you, and your account. https://nalet.github.io/design-system/patterns/top-bar/
- app navigation: Side navigation for an app's views, and when tabs are the better fit. https://nalet.github.io/design-system/patterns/app-navigation/
- home & tiles: The home page: one page of tiles in a few fixed groups, found with the search in the top bar, and when something gets a tile. https://nalet.github.io/design-system/patterns/home-and-tiles/
- settings and setup: Where each kind of setting lives, and the one place it is changed. https://nalet.github.io/design-system/patterns/settings-and-setup/
- status vocabulary: One status per item, in words people understand, the same everywhere. https://nalet.github.io/design-system/patterns/status-vocabulary/
- message handling: Where each message goes, so that every thing is said once, in the place that fits it. https://nalet.github.io/design-system/patterns/message-handling/
- empty states: What a list says when it has nothing to show: five kinds of empty, and the way forward from each. https://nalet.github.io/design-system/patterns/empty-states/
- loading and progress: What to show while people wait: nothing for a blink, then the loader, a value, or the shape of the content. https://nalet.github.io/design-system/patterns/loading-and-progress/
- selection and bulk actions: Ticking the rows to act on, and acting on all of them at once. https://nalet.github.io/design-system/patterns/selection-and-bulk-actions/
- forms and settings: Switches that apply at once, forms that wait for save, and errors that say how to fix them. https://nalet.github.io/design-system/patterns/forms-and-settings/
- tv focus: How the one focused thing on a TV screen stands out from across the room: a ring, a lighter surface and a little growth. https://nalet.github.io/design-system/patterns/tv-focus/

## glossary — https://nalet.github.io/design-system/get-started/glossary/ (as data: https://nalet.github.io/design-system/glossary.json)
- 10-foot: Made to be used from a sofa, about three metres (ten feet) away, with a remote control instead of a mouse or a touch screen. TV apps are 10-foot screens: their text, focus and spacing are larger and stronger than on a laptop.
- accessibility: Making sure everyone can use a screen, including people who use a keyboard instead of a mouse, a screen reader, or have low vision.
- accessible name: The name a screen reader announces for a control, like “save changes” for a button. It usually comes from the visible label; a control without visible words needs a name written for it.
- addon: An app that is installed into the platform on its own, after the platform itself. It brings its own tile and its own setup.
- AI agent: A program built on a large language model that carries out a piece of work on its own, such as writing code and the text of an interface, and then checks its results. People give it the work as a prompt.
- app: A part of the product with its own job, such as managing downloads or browsing the catalogue. It opens inside the shell.
- app icon: The small square picture that stands for the product on a phone’s home screen, in a browser tab or in a dock.
- ARIA: A set of attributes that tell assistive technology what an element is and what state it is in, where plain HTML can’t say it.
- assistive technology: Software and devices people use to work with a computer in their own way, such as screen readers, screen magnifiers, voice control and switches.
- automation: Work the system does by itself, without someone clicking a button each time.
- avatar: The small square with your picture or your initials that stands for you on the screen.
- backlog: Everything that is still to do, including the items that are not urgent.
- banner: A bar above a list or a page with a message about all of it, such as a warning that some items can’t be checked. It stays as long as the message is true.
- body face: The typeface for longer text that people read, like descriptions and messages. Ours is Inter.
- breakpoint: A width at which a layout changes, for example from two columns to one.
- bulk action: One action applied to many selected items at once, such as grabbing eight episodes in one go.
- bundle: The files a build tool packs together for the browser to download when an app opens.
- canvas: The dark background of every screen, and the few slightly lighter steps of it that panels sit on.
- changelog: The list of what changed in each version.
- chevron: The › sign. It is the brand’s mark, always in blue, and reads like the prompt of a terminal: this is where something starts.
- chrome: The parts of a screen that frame and operate the content, such as titles, buttons, tabs, menus and labels, as opposed to the content itself.
- component: A reusable building block of a screen, such as a button, a table or a message. It is built once and used everywhere, so it looks and behaves the same in every app.
- contrast ratio: How much a colour stands out from the colour behind it. Text needs enough contrast (at least 4.5 to 1) to be readable for people with low vision.
- CSS: The language that describes how a web page looks: its colours, sizes, fonts, spacing and layout.
- CSS custom property: A named value in CSS, such as --cloud-blue, that other styles refer to. It is how the design tokens reach a page.
- density: How tightly a screen is packed. A dense table has less space around each row, so more rows fit on the screen at once.
- design system: A shared set of rules, building blocks and examples that a team uses to make screens look and work the same way. It saves people from solving the same problem twice.
- design token: A named value, such as a colour, a size or a font, stored once and used by every component. Changing the token changes every place that uses it.
- disabled: A control that is shown but can’t be used right now. It is dimmed, and the keyboard passes over it.
- disclosure: A control that shows or hides more content below it, like “details”. A small arrow turns as it opens.
- dp: Density-independent pixels, the layout unit of Android and Android TV. A TV screen is 960 × 540 dp whatever its resolution, so on a 1920 × 1080 screen 1 dp is 2 pixels.
- drill-down: A more detailed view you open from a summary, for example the full list behind a number.
- easing: How a movement speeds up and slows down. “Ease” starts and ends gently; “linear” keeps one speed throughout.
- ellipsis: The three dots (…) that show where text was cut short because it didn’t fit.
- emphasized action: The one button on a screen that stands out, usually filled with colour. It is the step most people take next.
- empty state: What a list or a page shows when it has nothing to show: a simple picture, a line that says why, and what to do next.
- exception: Something that did not go as expected and needs a person, for example a download that failed. The opposite of the routine work the system handles alone.
- facet: One property a list can be filtered by, such as status or quality, with a few values to pick from.
- fallback font: The font a browser uses when the intended one hasn’t loaded: the next one in the list, down to the computer’s own.
- federated module: An app that is built and released on its own, but loaded into the shell’s page while it runs, so it appears inside the shell.
- focus: The highlight on the element a keyboard is currently on. Pressing Tab moves it to the next button or field.
- forced colours: A high-contrast setting in some operating systems that replaces a page’s colours with a few the person chose. Anything shown only by a fill or a shadow can disappear in it.
- glyph: A small symbol drawn as part of the text, such as a check, a cross or a triangle.
- hairline: A line one pixel wide, used for frames, rules and dividers.
- heading level: A heading’s rank, from 1 for the page’s title down to 6. Screen-reader users move through a page by its headings, so the levels follow the page’s outline.
- home: The first page you see when you sign in, with a tile for each app you can open.
- hover: Resting the mouse pointer on something without clicking it. Touch screens and keyboards have no hover, so nothing may depend on it alone.
- landmark: A named region of a page, such as the navigation or the main content. Screen-reader users can jump straight to it.
- leading edge: The side where reading starts: the left edge in English and other languages written from left to right.
- letter-spacing: Extra space between the letters of a word. Small labels get a little more so they stay readable; large titles get a little less.
- live region: A part of the page that a screen reader reads out when its text changes, without people having to go there. Counts and short messages use one.
- lockup: The brand’s mark and its name, set together in a fixed arrangement and used as one logo.
- millisecond: A thousandth of a second, written ms. A change that takes 120 ms feels immediate, yet the eye still sees it happen.
- mixed state: A checkbox that is neither on nor off, drawn with a dash. It means that some, but not all, of the options it stands for are on.
- monospace: A typeface where every letter has the same width, like on an old typewriter or in a terminal. We use it for titles, labels and codes.
- native element: A control the browser provides itself, such as a button, a checkbox or a select. It comes with keyboard and screen-reader support built in.
- number tile: A tile that shows a number someone acts on, such as 3 downloads that need attention. Pressing it opens the app, showing just those things.
- overflow menu: A menu that holds the actions that don’t fit in a row, behind one button such as “more actions”.
- page layout: A whole page, put together the same way for one kind of task, such as working through a list or editing settings. Pages of the same kind then feel familiar.
- pattern: A proven way to combine components to solve a recurring problem, like showing a list of things to do or asking for settings.
- peer dependency: A package an app installs itself, next to this one, so the app and the design system share one copy of it.
- placeholder: Pale example text inside an empty field. It disappears as soon as people type, so it can’t take the place of a label.
- playground: A live example on the React subsite where you can change a component’s settings and see the result straight away.
- pop-in: How a table makes room when it is narrow: its less important columns leave the header row, and their values show under each row’s name instead.
- portal: The website you sign in to first. It holds the shell, the home page and every app.
- principle: A short statement of what we value. When two good ideas compete, the principles help decide which one wins.
- prompt: The instruction a person gives an AI agent: what to build or change, and often why. It describes the work, not the words the finished screen should show.
- prop: A setting passed to a component in code, such as its size or its label.
- React: A widely used JavaScript library for building user interfaces. The components of this design system are written in it.
- React subsite: The part of this documentation for developers: every component’s live examples, its code, its settings and how it is built.
- reduced motion: A setting on phones and computers for people who get dizzy or distracted by animation. We stop movement when it is on.
- repository: The place where the code and the history of every change to it are kept. This one is public, on GitHub.
- row header: The cell that names a row, usually the first one, such as an episode’s code. Screen readers read it out with every other cell of that row.
- safe area: The part of a TV picture that every TV shows in full. Some TVs cut off a few percent at the edges, so text and everything that can take focus stays at least 5% away from them.
- screen reader: Software that reads a screen out loud, used by people who are blind or have low vision.
- secret: A password or a key that lets one system sign in to another. It is stored safely and never shown again; it can only be replaced.
- selection toolbar: The bar above a list that shows how many items are selected, and the actions that apply to all of them.
- semantic state: One of five meanings a status or a message can have: neutral, information, success, warning or error. Its colour and its symbol follow from the meaning.
- semantic versioning: Version numbers in three parts, like 0.3.1. Which part changes says how big the change is: the first for changes that break things, the second for new features, the last for fixes.
- sentence case: Writing with a capital letter only at the start of a sentence and for names, like this sentence.
- shell: The frame around every app: sign-in, the bar at the top, notifications and settings. Apps open inside it, so moving between them feels like one product.
- side navigation: A list of an app’s views down the left side of the screen. It stays visible, so you always see where you are and where you can go.
- skeleton: Grey blocks in the shape of the content that is about to appear, shown while a list or a page loads for the first time.
- speech input: Software that lets people control a computer by talking to it, for example by saying the name of a button to press it.
- status: A short word that says what state something is in, like “ready” or “needs attention”. Its colour tells you how urgent it is.
- status vocabulary: The fixed list of statuses one kind of item can have, with the words and the meaning of each. It is written down once and used everywhere the item appears.
- sticky header: A header that stays at the top while the content scrolls underneath it, so its labels stay in view.
- tab stop: A place the Tab key stops at as it moves through a page. A group of controls that is one tab stop is entered with one press of Tab; the arrow keys then move inside it.
- tabs: A row of labels above content that switch between parts of the same thing, like the overview and the history of one item.
- tabular figures: Digits that all have the same width, so the numbers in a column line up and a changing count doesn’t push the text beside it.
- tarball: One packed file that holds a release of the package, ready to install.
- target size: The area you can click or tap to use a control. A bigger target is easier to hit on a touch screen, or with an unsteady hand.
- task tile: A tile that starts one frequent task straight away, such as requesting a title, instead of opening an app on its first view.
- thousands separator: The comma in 2,500 that groups the digits in threes, so a long number can be read at a glance.
- tile: A square on the home page that opens an app. It can also show a number that needs attention.
- tile group: A set of tiles on the home page under one title, such as apps or settings. People look for their group first, then for the tile.
- tint: A faint wash of colour behind something, like the pale amber behind a warning.
- toast: A short message that pops up for a few seconds to confirm that something just happened, such as “8 episodes queued”. It goes away on its own.
- top bar: The bar across the top of every screen, with the product name, the search, notifications and your account menu. It is the same everywhere.
- trigger: The button that opens something, such as a menu or a list of options.
- type role: A named text style, such as a page title or body text, whose typeface, size, weight and spacing are decided once.
- user menu: The menu behind your initials or picture at the top right of every screen. It holds your account, settings, help and sign out.
- validation: Checking the values in a form before they are saved, and saying which ones need a fix and how.
- view: One screen inside an app, such as a list of downloads or a settings form.
- viewport: The part of a page you can see at once, in a browser window or on a phone’s screen.
- WCAG: The Web Content Accessibility Guidelines: the international standard for accessible websites. “AA” is the level most organisations aim for.
- weight: How thick the strokes of a typeface are. 400 is regular, 600 semi-bold and 700 bold.
- wordmark: A name written in a set typeface and used as a logo.
- worklist: A page that lists things someone needs to look at or act on, with filters, a count for each group and actions for several items at once.