Design Language - defuss-shadcn

On this page (6)

§The three questions

1. What does the user do? Read, choose or edit, move around, or get told something. Reading needs no controls; every control you add is something to learn. 2. What shape is the data? One value, records, a hierarchy, links between things, values over time, keys with values, places. The shape picks the family. 3. How much? Up to a few hundred elements, render all of it: the browser's find, print and accessibility tools work on the whole. Beyond that, take a windowed component - it draws the rows in view and runs every query over all of them (a million rows).

§Data you show

When you need	Use	Why	Skills · folders
One number or a status - a KPI, a total, a health	Statistic · Badge · Indicator · Progress · Radial Progress · Tacho	one glance; a meter or a needle when the range matters	`statistic` `badge` `indicator` `progress` `radial-progress` `tacho` · `data-display/` `feedback-status/` `multimedia/`
A few records that fit the page (up to a few hundred)	Table · Card · Timeline	all in the DOM: find in page, print, no script	`table` `card` `timeline` · `data-display/`
Thousands to a million records - sorted, filtered, selected	Data Grid · Virtual List · Big Data	windowed: only the rows in view are drawn, every query runs over all rows	`data-grid` `virtual-list` `chart` · `big-data/` `charts/`
A directory tree or a small hierarchy	Tree View · Collapsible	native details, keys of the tree pattern	`tree-view` `collapsible` · `data-display/`
A big hierarchy, or a hierarchy with columns	Data Tree · Tree Grid	windowed; branches open on demand	`data-tree` `data-grid` · `big-data/`
Linked data to explain - an architecture, a flow, a few dozen nodes	Illustrative Diagrams · Mermaid	drawn to make one point, step by step if needed	`diagram` `mermaid` · `diagrams/`
Linked data to explore - thousands to millions of nodes	Graph Explorer	semantic zoom, a worker lays out what is near	`graph-explorer` · `graphs/`
A time series - values over time	Change over time · Chart	lines and areas; one chart morphs between views	`chart` · `charts/`
Events in time - a history, a schedule, a recording	Timeline · Calendar · Media Timeline	a list of moments, a month, a ruler under a player	`timeline` `calendar` `media-timeline` · `data-display/` `multimedia/`
Values not over time - a comparison, a share, a distribution	Comparison · Composition · Distribution	the chart form follows the question asked	`chart` · `charts/`
Associative data - an object, metadata, settings (key and value)	Property Grid · Table	one row per key; the Property Grid edits in place	`property-grid` `table` · `application/` `data-display/`
Evaluation results - scores per case, pass and fail, a run against a run	Data Grid · Badge · Comparison · Diff	filter the failures, rank the scores, compare two runs	`data-grid` `badge` `chart` `diff` · `big-data/` `data-display/` `charts/`
Two versions of one thing	Diff	before and after, side by side or inline	`diff` · `data-display/`
Places, regions and routes	Geo Map	equal-area projections, regions to select, routes on a graph	`geo-map` · `geography/`
Formulas and their results	Formula Rendering · Compute & Explain	typeset TeX; a computation with its conditions	`math-renderer` `math-compute` · `math/`
Code and terminal output	Code · HTML Preview Editor	a window to read; a live preview to run	`mockup-code` `code-example` · `mockup/` `wysiwyg-editors/`
Long text - an article, a report, a paper	Typography · Modern Paper · Table of Contents	a reading measure, a contents list that follows	`typography` `paper` `toc` · `primitives/` `papers/` `navigation/`

§Input you take

When you need	Use	Why	Skills · folders
On or off	Switch · Checkbox · Toggle	a setting that applies now; a choice in a form; a pressed tool	`switch` `checkbox` `toggle` · `forms-inputs/` `actions/`
One of two to four, cycled with one click	Swap · Language Switcher	the next value is one click away	`swap` `language-switcher` · `actions/` `navigation/`
One of three to seven, all in view	Radio Group · Toggle Group	every option visible, no list to open	`radio` `toggle-group` · `forms-inputs/` `actions/`
One of many	Select · Combobox	native up to a dozen or so; with more, a search field	`select` `combobox` · `forms-inputs/`
One of thousands, or from a server	Autocomplete · Command	debounced requests, the last one wins	`autocomplete` `command` · `big-data/` `overlays/`
Several of many	Checkbox · Combobox	a short list as boxes; a long one as tags	`checkbox` `combobox` · `forms-inputs/`
A number or an amount	Number Input · Slider · Knobs · Rating	typed, dragged, turned or tapped	`number-input` `slider` `knob` `rating` · `forms-inputs/` `multimedia/`
A date, a color, a file, a code	Date Picker · Color Picker · File Input · OTP Input	native controls under a consistent look	`date-picker` `color-picker` `file-input` `otp-input` · `forms-inputs/`
A short or a long text	Input · Textarea	validation by the browser, the textarea grows with its text	`input` `textarea` · `forms-inputs/`
A record - several fields, maybe several steps	Form · Questionnaire	native validation; branches and drafts when the answers decide the way	`form` `questionnaire` · `forms-inputs/` `questionnaire/`
Many records in place	Data Grid	the cell edits, the query keeps its filters	`data-grid` · `big-data/`
Rich text and comments on it	Editor.js · Document Comments	blocks with Markdown in and out; comments anchored in the text	`editorjs` `doc-comments` · `wysiwyg-editors/` `application/`
A formula	Formula Editing	a math field over a textarea that stays the form control	`math-editor` · `math/`
A page, visually	Visual Editor · HTML Preview Editor	drag blocks; or edit the source next to its preview	`visual-editor` `code-example` · `wysiwyg-editors/`

§Moving around

When you need	Use	Why	Skills · folders
The main sections of a site or an app	Navbar · Navigation Menu · Sidebar · Dock	always in view; a sidebar when there are many	`navbar` `navigation-menu` `sidebar` `dock` · `navigation/` `application/`
Where am I - and the way up or through the page	Breadcrumb · Table of Contents	the path; the sections of a long page	`breadcrumb` `toc` · `navigation/`
Peer views of one thing	Tabs · Accordion	one view at a time; several open at once	`tabs` `accordion` · `navigation/` `overlays/`
A long result in parts	Pagination · Virtual List	pages to address; one scroll for everything	`pagination` `virtual-list` · `navigation/` `big-data/`
A sequence of steps	Steps · Questionnaire	where the user is and what is left	`steps` `questionnaire` · `navigation/` `questionnaire/`
Commands - from anywhere, on a thing, in a menu bar	Command · Context Menu · Dropdown Menu · Menubar	search every action; the actions of one item; an app menu	`command` `context-menu` `dropdown` `menubar` · `overlays/` `navigation/`
The language and the theme	Language Switcher · Theme Switcher	the page language through defuss-i18n; a theme as one stylesheet	`language-switcher` `theme-switcher` · `navigation/`
A workspace the user arranges	Border Layout · Panel · Resizer · Window	regions that fold, panels that stack, windows that move	`border-layout` `panel` `resizer` `window` · `application/`

§Telling the user

When you need	Use	Why	Skills · folders
Something happened - no answer needed	Toast	it goes by itself; the page stays usable	`toast` · `feedback-status/`
A state of one part of the page	Alert · Badge	in place, as long as the state lasts	`alert` `badge` · `feedback-status/` `data-display/`
An answer is required before going on	Alert Dialog	modal - the one case that blocks the page	`alert-dialog` · `feedback-status/`
A focused task over the page	Dialog · Sheet	a form or a detail without leaving the page	`dialog` `sheet` · `overlays/`
More detail on demand	Popover · Tooltip · Collapsible	a hint on hover, a panel on click, a section that opens	`popover` `tooltip` `collapsible` · `overlays/` `data-display/`
Waiting	Spinner · Skeleton · Progress	unknown time; the shape of what comes; a known share	`spinner` `skeleton` `progress` · `feedback-status/`

§Rules of thumb

The platform first. A native control - select, details, dialog, a checkbox - brings its keys, its form value and its accessibility with it. Take the scripted component when the native one cannot do the job: a search over many options, a windowed list, a tree with columns. See Native Web APIs.

Show before you hide. Two to seven options fit on screen: radios, a toggle group, tabs. A list that opens costs a click and hides the choice; a modal costs the whole page. Open a dialog only for a focused task, and an alert dialog only when the answer is required.

Search from eight. This system offers a search field once a list holds more than seven options: the Combobox, the Language Switcher from eight languages, the Command palette for a whole app.

Explain small, explore big. An Illustrative Diagram makes one point with a few dozen boxes and can reveal it step by step. When the reader has to find their own way through thousands of nodes, the Graph Explorer zooms by meaning and loads what is near.

Interactive only where it pays. A chart that makes one point stays still and says it in its title (Narrative); a chart for exploring gets tooltips, zoom and a grid that filters it. Every interaction is something to discover, to learn and to keep working.

One look, one language. Variants and sizes are data attributes on the same classes, and every component reads the same tokens, so a page built from several of them looks like one thing - see Data Attribute API and Theming. An agent finds each component's markup in its skill; the whole system is one skill, skills/defuss-shadcn/SKILL.md (Component Skills).

Comments, ideas or improvements? Edit this page's source on GitHub