@spark-web/badge 5.1.0 → 5.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/CLAUDE.md +114 -0
  3. package/package.json +4 -3
package/CHANGELOG.md CHANGED
@@ -1,5 +1,19 @@
1
1
  # @spark-web/badge
2
2
 
3
+ ## 5.1.1
4
+
5
+ ### Patch Changes
6
+
7
+ - [#782](https://github.com/brighte-labs/spark-web/pull/782)
8
+ [`bb41800`](https://github.com/brighte-labs/spark-web/commit/bb418004d21165f72f4bf2456afea844ee04a21c)
9
+ Thanks [@jacobporci-brighte](https://github.com/jacobporci-brighte)! -
10
+ **docs:** include CLAUDE.md in published package files
11
+
12
+ - Updated dependencies
13
+ [[`bb41800`](https://github.com/brighte-labs/spark-web/commit/bb418004d21165f72f4bf2456afea844ee04a21c)]:
14
+ - @spark-web/box@6.0.1
15
+ - @spark-web/text@5.3.1
16
+
3
17
  ## 5.1.0
4
18
 
5
19
  ### Minor Changes
package/CLAUDE.md ADDED
@@ -0,0 +1,114 @@
1
+ # @spark-web/badge — AI Context
2
+
3
+ ## What this is
4
+
5
+ A status indicator pill that combines a colored dot with a text label. Used to
6
+ communicate categorical status on a record or field. The dot is the primary
7
+ visual signal; the label provides the text description.
8
+
9
+ This package also exports `IndicatorDot` — a standalone dot without a label,
10
+ used when space is too constrained for a full badge.
11
+
12
+ ## What this is NOT
13
+
14
+ - Not `StatusBadge` — `StatusBadge` is a colored background pill with no dot;
15
+ use `Badge` when the dot indicator is the primary visual signal
16
+ - Not a button or interactive element — display-only
17
+ - Not a notification counter — use a different component for numeric counts
18
+
19
+ ## Props interface
20
+
21
+ ### `Badge`
22
+
23
+ | Prop | Type | Default | Notes |
24
+ | ---------- | -------------------------------------------------------------------------- | ----------- | ------------------------- |
25
+ | `tone` | `'accent' \| 'caution' \| 'critical' \| 'info' \| 'neutral' \| 'positive'` | `'neutral'` | Controls the dot color |
26
+ | `children` | `string \| number` | required | The label text |
27
+ | `data` | `DataAttributeMap` | — | Test/analytics attributes |
28
+
29
+ ### `IndicatorDot`
30
+
31
+ | Prop | Type | Notes |
32
+ | ------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------- |
33
+ | `tone` | `'accent' \| 'caution' \| 'critical' \| 'info' \| 'neutral' \| 'positive'` | required — controls dot color |
34
+ | `label` | `string` | Supply when the intent isn't conveyed by surrounding text (a11y) |
35
+ | `data` | `DataAttributeMap` | Test/analytics attributes |
36
+
37
+ ## Token usage
38
+
39
+ All values from `useTheme()` from `@spark-web/theme`. Never use raw hex, px, or
40
+ Tailwind.
41
+
42
+ ### Badge
43
+
44
+ | Property | Token / Value |
45
+ | ---------------- | --------------------------------------------------------- |
46
+ | Display | `display="inline-flex"` (Box prop) |
47
+ | Alignment | `alignItems="center"` (Box prop) |
48
+ | Background | `background="surface"` — always white, regardless of tone |
49
+ | Border | `border="standard"` (Box prop) |
50
+ | Border radius | `borderRadius="full"` (Box prop) |
51
+ | Dot-to-label gap | `gap="xsmall"` (Box prop) |
52
+ | Height | `height="xsmall"` (Box prop) |
53
+ | Horizontal pad | `paddingX="small"` (Box prop) |
54
+ | Text size | `size="xsmall"` (Text prop) |
55
+ | Text overflow | `overflowStrategy="nowrap"` (Text prop) |
56
+
57
+ ### IndicatorDot
58
+
59
+ | Property | Token / Value |
60
+ | ------------- | -------------------------------------------------------------- |
61
+ | Dot color | `theme.color.status[tone]` via `useTheme()` — inline CSS |
62
+ | Dot size | `8×8px` inline CSS — no Spark size token; documented exception |
63
+ | Border radius | `borderRadius="full"` (Box prop) |
64
+
65
+ ### IndicatorContainer (internal, not exported)
66
+
67
+ The dot is wrapped in a container sized to match the text cap-height so the dot
68
+ and label align vertically. This uses `theme.typography.text[size].capHeight`
69
+ via `responsiveStyles` — do not replicate this in consuming code.
70
+
71
+ ## Tone → dot color mapping
72
+
73
+ | Tone | Color source |
74
+ | ---------- | ----------------------------- |
75
+ | `accent` | `theme.color.status.accent` |
76
+ | `caution` | `theme.color.status.caution` |
77
+ | `critical` | `theme.color.status.critical` |
78
+ | `info` | `theme.color.status.info` |
79
+ | `neutral` | `theme.color.status.neutral` |
80
+ | `positive` | `theme.color.status.positive` |
81
+
82
+ For tone selection rules on admin surfaces, see
83
+ `node_modules/@spark-web/design-system/patterns/internal-admin/CLAUDE.md`.
84
+
85
+ ## Badge vs StatusBadge — decision rule
86
+
87
+ | Signal needed | Use |
88
+ | ------------------------- | -------------- |
89
+ | Dot is the primary signal | `Badge` |
90
+ | Colored pill, no dot | `StatusBadge` |
91
+ | Standalone dot, no label | `IndicatorDot` |
92
+
93
+ For internal-admin surfaces, always use `Badge` in table status columns — see
94
+ `node_modules/@spark-web/design-system/patterns/internal-admin/CLAUDE.md`.
95
+
96
+ ## Composition
97
+
98
+ - `Box` from `@spark-web/box` — outer pill, indicator container, dot
99
+ - `Text` from `@spark-web/text` — label at `size="xsmall"`
100
+ - `useTheme()` from `@spark-web/theme` — dot color and cap-height alignment
101
+
102
+ ## Do NOTs
103
+
104
+ - NEVER use raw hex, px, or Tailwind for any visual property
105
+ - NEVER change `background="surface"` on `Badge` — the pill is always white;
106
+ tone only controls the dot color
107
+ - NEVER use `Badge` when a colored pill is needed — use `StatusBadge`
108
+ - NEVER use `tone="pending"` — there is no `pending` tone; use `tone="info"` for
109
+ pending/awaiting states
110
+ - NEVER use long label text — text is `nowrap` and will overflow without
111
+ wrapping
112
+ - NEVER make `Badge` or `IndicatorDot` interactive — they are display-only
113
+ - NEVER omit `label` on a standalone `IndicatorDot` when surrounding text does
114
+ not convey the status meaning
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@spark-web/badge",
3
- "version": "5.1.0",
3
+ "version": "5.1.1",
4
4
  "homepage": "https://github.com/brighte-labs/spark-web#readme",
5
5
  "repository": {
6
6
  "type": "git",
@@ -11,14 +11,15 @@
11
11
  "module": "dist/spark-web-badge.esm.js",
12
12
  "files": [
13
13
  "CHANGELOG.md",
14
+ "CLAUDE.md",
14
15
  "dist",
15
16
  "README.md"
16
17
  ],
17
18
  "dependencies": {
18
19
  "@babel/runtime": "^7.25.0",
19
20
  "@emotion/react": "^11.14.0",
20
- "@spark-web/box": "^6.0.0",
21
- "@spark-web/text": "^5.3.0",
21
+ "@spark-web/box": "^6.0.1",
22
+ "@spark-web/text": "^5.3.1",
22
23
  "@spark-web/theme": "^5.13.0",
23
24
  "@spark-web/utils": "^5.1.0"
24
25
  },