UNPKG

@spark-web/design-system

Version:

--- title: Design System ---

127 lines (87 loc) • 4.53 kB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
# Internal admin — interaction and pattern rules These rules apply to all components and patterns built for internal admin surfaces. They sit above individual component rules. When a conflict exists between these rules and a component-level CLAUDE.md, these rules take precedence for admin surfaces. --- ## Row interaction rules ### Clickable rows A row is clickable when the data model has a record-level detail view or destination page. The agent must determine this from the PRD: - If the PRD describes a detail page, record view, or drill-down → row is clickable - If the PRD describes a read-only data display with no record destination → row is not clickable - If unsure, default to clickable ### Hover state Hover state is determined entirely by whether the row is clickable: - Row is clickable → hover state is applied when the cursor is over the row, **except** when hovering a button within the row (e.g. the MeatballMenu trigger) - Row is not clickable → hover state is never applied, no exceptions Never apply a hover state to a non-clickable row. It implies interactivity that does not exist and misleads the user. When a clickable row contains a MeatballMenu, the row hover must be suppressed while the cursor is over the meatball button. Two competing hover targets (row and menu trigger) confuse the user about what will happen on click. Implement using CSS `:has()` on the `<tr>` — see `@spark-web/data-table` CLAUDE.md for the exact pattern. --- ## Overflow menu rules An overflow menu on a row is used only when ALL of the following are true: - There are 2 or more actions that apply to the row record - The actions relate only to that specific record, not to the page or table Use this decision tree: ``` Does the row have actions? No → no overflow menu, no action column Yes → how many actions? 1 action + row is NOT clickable → inline button or icon 1 action + row IS clickable → overflow menu 2+ actions → always overflow menu ``` Never place inline action buttons alongside a clickable row. A clickable row and inline buttons create two competing interaction targets and confuse the user about what clicking does. --- ## Badge and pill rules A badge or pill is used only when: - The field represents a status with 2 or more distinct values - The status values have meaningful visual distinction (e.g. active vs inactive, pending vs approved vs rejected) Do not use a badge when: - The field is free-form text - The field is a boolean with no meaningful status distinction - There is only one possible value ### Badge tone mapping This mapping is authoritative for the internal-admin surface. If a component CLAUDE.md defines tone guidance, the mapping below takes precedence. Map status values to tones using this logic derived from the PRD: - Positive / active / approved / complete → `positive` tone - Warning / approaching limit / expiring → `caution` tone - Critical / rejected / failed / overdue / suspended → `critical` tone - Neutral / inactive / archived / unknown → `neutral` tone - Pending / in review / awaiting approval → `info` tone **Caution vs info (pending):** Use `caution` for warnings that are time-sensitive or approaching a limit. Use `info` for states where a record is waiting on a human decision or review (e.g. "Pending approval", "Under review"). Component choice: - Always use `<Badge>` (dot + label) for status columns in list-page tables — never `<StatusBadge>` - Use `<StatusBadge>` (colored pill, no dot) only in page headers and section headers via their `statusBadge` prop — never in table status columns Available tones for both components: `accent | caution | critical | info | neutral | positive`. There is no `pending` tone — always use `info` for pending/awaiting states. When in doubt, use `neutral`. Never invent a tone that does not exist in the Spark Web theme. --- ## Rules that update as the system grows When a new pattern or component is added to the internal admin surface, update this file with any new interaction rules that apply globally. Do not duplicate rules that already exist here in component-level CLAUDE.md files. Then open the root CLAUDE.md and append this line to the Architecture section: ## Pattern library Agent pattern and surface rules live in node_modules/@spark-web/design-system/patterns/. Always read node_modules/@spark-web/design-system/patterns/CLAUDE.md before any build task.