@cognitap/radiant 0.0.1 → 0.0.3

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 (192) hide show
  1. package/CHANGELOG.md +323 -15
  2. package/LICENSE +1 -1
  3. package/README.md +963 -220
  4. package/RELEASE_POLICY.md +23 -95
  5. package/dist/library/Accordion.d.ts +56 -0
  6. package/dist/library/Accordion.d.ts.map +1 -0
  7. package/dist/library/Accordion.js +89 -0
  8. package/dist/library/Accordion.js.map +1 -0
  9. package/dist/library/Button.d.ts +25 -3
  10. package/dist/library/Button.d.ts.map +1 -1
  11. package/dist/library/Button.js +31 -3
  12. package/dist/library/Button.js.map +1 -1
  13. package/dist/library/Card.d.ts +31 -0
  14. package/dist/library/Card.d.ts.map +1 -0
  15. package/dist/library/Card.js +69 -0
  16. package/dist/library/Card.js.map +1 -0
  17. package/dist/library/Checkbox.d.ts +13 -0
  18. package/dist/library/Checkbox.d.ts.map +1 -0
  19. package/dist/library/Checkbox.js +77 -0
  20. package/dist/library/Checkbox.js.map +1 -0
  21. package/dist/library/Collapsible.d.ts +32 -0
  22. package/dist/library/Collapsible.d.ts.map +1 -0
  23. package/dist/library/Collapsible.js +99 -0
  24. package/dist/library/Collapsible.js.map +1 -0
  25. package/dist/library/Dialog.d.ts +50 -0
  26. package/dist/library/Dialog.d.ts.map +1 -0
  27. package/dist/library/Dialog.js +215 -0
  28. package/dist/library/Dialog.js.map +1 -0
  29. package/dist/library/Field.d.ts +68 -0
  30. package/dist/library/Field.d.ts.map +1 -0
  31. package/dist/library/Field.js +114 -0
  32. package/dist/library/Field.js.map +1 -0
  33. package/dist/library/Input.d.ts +10 -0
  34. package/dist/library/Input.d.ts.map +1 -0
  35. package/dist/library/Input.js +51 -0
  36. package/dist/library/Input.js.map +1 -0
  37. package/dist/library/Link.d.ts +27 -0
  38. package/dist/library/Link.d.ts.map +1 -0
  39. package/dist/library/Link.js +50 -0
  40. package/dist/library/Link.js.map +1 -0
  41. package/dist/library/RadioGroup.d.ts +27 -0
  42. package/dist/library/RadioGroup.d.ts.map +1 -0
  43. package/dist/library/RadioGroup.js +103 -0
  44. package/dist/library/RadioGroup.js.map +1 -0
  45. package/dist/library/ThemeScope.d.ts +10 -0
  46. package/dist/library/ThemeScope.d.ts.map +1 -0
  47. package/dist/library/ThemeScope.js +41 -0
  48. package/dist/library/ThemeScope.js.map +1 -0
  49. package/dist/library/actionStyles.d.ts +11 -0
  50. package/dist/library/actionStyles.d.ts.map +1 -0
  51. package/dist/library/actionStyles.js +75 -0
  52. package/dist/library/actionStyles.js.map +1 -0
  53. package/dist/library/cn.d.ts +1 -2
  54. package/dist/library/cn.d.ts.map +1 -1
  55. package/dist/library/cn.js +1 -8
  56. package/dist/library/cn.js.map +1 -1
  57. package/dist/library/controlStyles.d.ts +5 -0
  58. package/dist/library/controlStyles.d.ts.map +1 -0
  59. package/dist/library/controlStyles.js +15 -0
  60. package/dist/library/controlStyles.js.map +1 -0
  61. package/dist/library/index.d.ts +24 -1
  62. package/dist/library/index.d.ts.map +1 -1
  63. package/dist/library/index.js +11 -0
  64. package/dist/library/index.js.map +1 -1
  65. package/dist/library/internal/events.d.ts +8 -0
  66. package/dist/library/internal/events.d.ts.map +1 -0
  67. package/dist/library/internal/events.js +13 -0
  68. package/dist/library/internal/events.js.map +1 -0
  69. package/dist/library/internal/ids.d.ts +3 -0
  70. package/dist/library/internal/ids.d.ts.map +1 -0
  71. package/dist/library/internal/ids.js +6 -0
  72. package/dist/library/internal/ids.js.map +1 -0
  73. package/dist/library/internal/selection.d.ts +5 -0
  74. package/dist/library/internal/selection.d.ts.map +1 -0
  75. package/dist/library/internal/selection.js +18 -0
  76. package/dist/library/internal/selection.js.map +1 -0
  77. package/dist/library/presentation.d.ts +18 -0
  78. package/dist/library/presentation.d.ts.map +1 -0
  79. package/dist/library/presentation.js +2 -0
  80. package/dist/library/presentation.js.map +1 -0
  81. package/dist/library/react/useComposedRefs.d.ts +4 -0
  82. package/dist/library/react/useComposedRefs.d.ts.map +1 -0
  83. package/dist/library/react/useComposedRefs.js +28 -0
  84. package/dist/library/react/useComposedRefs.js.map +1 -0
  85. package/dist/library/react/useControllableState.d.ts +16 -0
  86. package/dist/library/react/useControllableState.d.ts.map +1 -0
  87. package/dist/library/react/useControllableState.js +29 -0
  88. package/dist/library/react/useControllableState.js.map +1 -0
  89. package/dist/library/react/useNativeOwner.d.ts +17 -0
  90. package/dist/library/react/useNativeOwner.d.ts.map +1 -0
  91. package/dist/library/react/useNativeOwner.js +17 -0
  92. package/dist/library/react/useNativeOwner.js.map +1 -0
  93. package/dist/library/reset.css +1 -0
  94. package/dist/library/styles.css +2 -1
  95. package/dist/library/themes/components.d.ts +217 -0
  96. package/dist/library/themes/components.d.ts.map +1 -0
  97. package/dist/library/themes/components.js +229 -0
  98. package/dist/library/themes/components.js.map +1 -0
  99. package/dist/library/themes/default.d.ts +2 -0
  100. package/dist/library/themes/default.d.ts.map +1 -0
  101. package/dist/library/themes/default.js +4 -0
  102. package/dist/library/themes/default.js.map +1 -0
  103. package/dist/library/themes/defineTheme.d.ts +33 -0
  104. package/dist/library/themes/defineTheme.d.ts.map +1 -0
  105. package/dist/library/themes/defineTheme.js +98 -0
  106. package/dist/library/themes/defineTheme.js.map +1 -0
  107. package/dist/library/themes/expressive.d.ts +2 -0
  108. package/dist/library/themes/expressive.d.ts.map +1 -0
  109. package/dist/library/themes/expressive.js +132 -0
  110. package/dist/library/themes/expressive.js.map +1 -0
  111. package/dist/library/themes/glass.d.ts +2 -0
  112. package/dist/library/themes/glass.d.ts.map +1 -0
  113. package/dist/library/themes/glass.js +132 -0
  114. package/dist/library/themes/glass.js.map +1 -0
  115. package/dist/library/themes/index.d.ts +14 -0
  116. package/dist/library/themes/index.d.ts.map +1 -0
  117. package/dist/library/themes/index.js +21 -0
  118. package/dist/library/themes/index.js.map +1 -0
  119. package/dist/library/themes/jelly.d.ts +2 -0
  120. package/dist/library/themes/jelly.d.ts.map +1 -0
  121. package/dist/library/themes/jelly.js +130 -0
  122. package/dist/library/themes/jelly.js.map +1 -0
  123. package/dist/library/themes/preset-values.d.ts +4 -0
  124. package/dist/library/themes/preset-values.d.ts.map +1 -0
  125. package/dist/library/themes/preset-values.js +5 -0
  126. package/dist/library/themes/preset-values.js.map +1 -0
  127. package/dist/library/themes/radiant.d.ts +2 -0
  128. package/dist/library/themes/radiant.d.ts.map +1 -0
  129. package/dist/library/themes/radiant.js +129 -0
  130. package/dist/library/themes/radiant.js.map +1 -0
  131. package/dist/library/themes/sharp-3d.d.ts +2 -0
  132. package/dist/library/themes/sharp-3d.d.ts.map +1 -0
  133. package/dist/library/themes/sharp-3d.js +142 -0
  134. package/dist/library/themes/sharp-3d.js.map +1 -0
  135. package/dist/library/themes/soft-squircle.d.ts +2 -0
  136. package/dist/library/themes/soft-squircle.d.ts.map +1 -0
  137. package/dist/library/themes/soft-squircle.js +131 -0
  138. package/dist/library/themes/soft-squircle.js.map +1 -0
  139. package/dist/library/themes/ticket.d.ts +2 -0
  140. package/dist/library/themes/ticket.d.ts.map +1 -0
  141. package/dist/library/themes/ticket.js +141 -0
  142. package/dist/library/themes/ticket.js.map +1 -0
  143. package/dist/library/themes/tokens.d.ts +100 -0
  144. package/dist/library/themes/tokens.d.ts.map +1 -0
  145. package/dist/library/themes/tokens.js +171 -0
  146. package/dist/library/themes/tokens.js.map +1 -0
  147. package/dist/library/themes/types.d.ts +2 -0
  148. package/dist/library/themes/types.d.ts.map +1 -0
  149. package/dist/library/themes/types.js +2 -0
  150. package/dist/library/themes/types.js.map +1 -0
  151. package/docs/accessibility.md +189 -0
  152. package/docs/system.md +218 -0
  153. package/docs/theming.md +392 -0
  154. package/package.json +28 -11
  155. package/src/Accordion.tsx +235 -0
  156. package/src/Button.tsx +95 -15
  157. package/src/Card.tsx +143 -0
  158. package/src/Checkbox.tsx +189 -0
  159. package/src/Collapsible.tsx +193 -0
  160. package/src/Dialog.tsx +333 -0
  161. package/src/Field.tsx +293 -0
  162. package/src/Input.tsx +82 -0
  163. package/src/Link.tsx +95 -0
  164. package/src/RadioGroup.tsx +255 -0
  165. package/src/ThemeScope.tsx +64 -0
  166. package/src/actionStyles.ts +90 -0
  167. package/src/cn.ts +1 -10
  168. package/src/controlStyles.ts +19 -0
  169. package/src/index.ts +93 -1
  170. package/src/internal/events.ts +17 -0
  171. package/src/internal/ids.ts +5 -0
  172. package/src/internal/selection.ts +20 -0
  173. package/src/presentation.ts +12 -0
  174. package/src/react/useComposedRefs.ts +32 -0
  175. package/src/react/useControllableState.ts +50 -0
  176. package/src/react/useNativeOwner.ts +33 -0
  177. package/src/styles.css +2 -14
  178. package/src/themes/baseline.css +116 -0
  179. package/src/themes/components.ts +249 -0
  180. package/src/themes/default.ts +4 -0
  181. package/src/themes/defineTheme.ts +145 -0
  182. package/src/themes/expressive.ts +132 -0
  183. package/src/themes/glass.ts +135 -0
  184. package/src/themes/index.ts +33 -0
  185. package/src/themes/jelly.ts +130 -0
  186. package/src/themes/preset-values.ts +5 -0
  187. package/src/themes/radiant.ts +129 -0
  188. package/src/themes/sharp-3d.ts +142 -0
  189. package/src/themes/soft-squircle.ts +131 -0
  190. package/src/themes/ticket.ts +141 -0
  191. package/src/themes/tokens.ts +262 -0
  192. package/src/themes/types.ts +10 -0
@@ -0,0 +1,189 @@
1
+ # Browser and accessibility verification
2
+
3
+ This is Radiant's support-target matrix and evidence process for the current
4
+ ten-family batch. It defines what to check and how to report it. A target is a
5
+ configuration we intend to verify; only a dated result identifies what passed.
6
+ DEV-134 audits harmonisation coverage, DEV-57 checks installed compositions, and
7
+ DEV-83 owns the complete-catalog release audit.
8
+
9
+ The reference is [WCAG 2.2 A/AA](https://www.w3.org/TR/WCAG22/).
10
+ Component tests contribute evidence; conformance applies to
11
+ [whole pages and complete processes](https://www.w3.org/TR/WCAG22/#conformance-reqs).
12
+ [Automated tools require human judgment](https://www.w3.org/WAI/test-evaluate/tools/selecting/#what-evaluation-tools-can-do-and-can-not-do).
13
+ This matrix supplies neither a library-wide conformance claim nor certification.
14
+
15
+ ## Targets and recorded coverage
16
+
17
+ For manual targets, use a stable browser/AT release on a vendor-supported OS.
18
+ Record the installed versions/builds, device and settings at the time of testing;
19
+ "latest" is a target-selection rule, never a version in an evidence record.
20
+ Record built-in VoiceOver against the exact OS version/build if a separate AT
21
+ version is unavailable. A desktop engine test does not verify a mobile browser,
22
+ and Playwright WebKit does not establish Safari/VoiceOver behavior.
23
+
24
+ | Target | Input / AT | Evidence as of 2026-10-25 |
25
+ | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
26
+ | Pinned Playwright Chromium on the local macOS host | Automated browser input and axe; no AT | Version-complete environment captured; execution result in [E47-local](https://github.com/cognitap/radiant/blob/main/docs/verification/2026-10-25-chromium.md) |
27
+ | Pinned Playwright Chromium on Linux CI | Same automated suite; no AT | Each new run records its own environment and JUnit report; inspect that run's artifacts |
28
+ | Windows + Firefox | Keyboard and NVDA | **Not run**; browser, OS and NVDA versions unrecorded |
29
+ | macOS + Safari | Keyboard and VoiceOver | **Not run**; installed OS availability is not a test result |
30
+ | iOS + Safari on a physical iPhone/iPad | Touch exploration and VoiceOver; external keyboard when claimed | **Not run**; device, OS/build, Safari and AT configuration unrecorded |
31
+ | Android + Chrome on a physical device | Touch exploration and TalkBack; external keyboard when claimed | **Not run**; device, OS/build, Chrome and TalkBack versions unrecorded |
32
+ | Desktop Chrome / Edge on supported Windows/macOS; Firefox and Safari on their supported desktop OS | Keyboard, zoom, visual rendering; real Windows contrast themes where applicable | **Not run as a version-complete manual matrix**; the historical Chrome review below is narrower evidence |
33
+
34
+ The [2026-10 Storybook audit](https://github.com/cognitap/radiant/blob/main/docs/storybook-audit-2026-10.md)
35
+ records earlier Chrome visual/interaction work and corrections. Its browser/OS
36
+ builds were not captured, and AT was explicitly outside its scope. Preserve that
37
+ history without promoting it to a version-complete browser or screen-reader pass.
38
+ The open manual rows are known evidence gaps, not failures observed on those systems.
39
+
40
+ ## Prepare a reproducible run
41
+
42
+ 1. Use a fixed revision and matching JavaScript/CSS. Record the package or source
43
+ revision, working-tree changes, CSS route (compiled or Tailwind), optional
44
+ reset, custom overrides and font loading. Installed-consumer evidence must
45
+ also identify its package version/archive integrity and fixture revision.
46
+ 2. Open the [canonical stories and assembled recipes](system.md#reuse-the-canonical-examples).
47
+ Inspect native and TanStack form owners, standalone/Card/Dialog placement,
48
+ and both default and replacement action paths. Use default Radiant parts in
49
+ the ordinary path so an adapter cannot hide a broken composition.
50
+ 3. Use the global Theme/Mode selectors. Disable autoplay for manual interactions
51
+ with `embed=true`; wait for the story scope, fonts and mode to settle. Check
52
+ Canvas and Docs when changing preview integration. See
53
+ [Storybook inspection](https://github.com/cognitap/radiant/blob/main/docs/storybook.md#verification).
54
+ 4. Record each tested preset/mode rather than writing "all themes" from a sample.
55
+ The visual target is every preset in explicit light/dark, relevant states,
56
+ and System preference switching. For each claimed browser/AT combination,
57
+ execute the applicable scenarios below; record sampled combinations and leave
58
+ the rest unverified. Recheck a defect's affected combinations after its fix.
59
+ 5. Capture OS/browser/AT versions and settings before acting. Include locale,
60
+ browser zoom, viewport, orientation, OS text/display scaling, keyboard access
61
+ and screen-reader mode/verbosity/gesture customisations. Record OS reduced
62
+ motion/contrast settings separately from browser emulation.
63
+
64
+ ## Manual scenarios
65
+
66
+ Run desktop keyboard cases with the screen reader off, then with it on.
67
+ Observe browser focus and the screen reader's reading cursor separately.
68
+ Record conveyed names/roles/states and actual announcements; exact speech wording
69
+ can vary by settings. The platform instructions below are operating guidance,
70
+ not results for Radiant.
71
+
72
+ | ID | Action and expected observation |
73
+ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
74
+ | K1 — actions | Tab/Shift+Tab through Button, Link and Dialog actions, including default/custom hosts. Enter/Space activate buttons; Enter follows a link, while Space keeps native anchor behavior. Pending/disabled actions retain their documented guards/cues. Press, move away, then release to check cancellation. Visible text is included in the accessible name. |
75
+ | K2 — forms | Read Field labels/help/required/error text and RadioGroup legend/options. Exercise text entry, checkbox checked/unchecked/mixed state, radio arrows/Space and disabled options. Submit invalid then valid data; hear the error relationship and saved/reset result. Reset restores the right owner and clears stale feedback in native and TanStack recipes. |
76
+ | K3 — Dialog | Open through default Trigger and a compatible replacement. Confirm name/description, appropriate initial focus, keyboard focus containment, background inertness, a reachable visible close action, Escape and focus restoration. Repeat with long content and a narrow viewport. Check nonmodal behavior separately; a modal's standard exit makes its contained Tab cycle legitimate. |
77
+ | K4 — disclosures | Enter/Space toggle native summary; expanded state and meaningful heading/order reach AT. Closed content is excluded from reading/focus navigation while remaining mounted. Check nested Collapsible and single/multiple Accordion, disabled sections and independent instances. Keep native summary behavior rather than inventing button or roving-focus rules. |
78
+ | K5 — composition | Complete Recipes → Workspace: open the profile Dialog, correct an error, save/reset, open Privacy/Data retention and follow its Link. Check Card's reading order/heading and contained actions without adding a focus stop to its passive wrapper. Test reused forms and actual navigation/form data, not only a rendered role. |
79
+ | V1 — palette and state | For every claimed theme/mode, inspect rest/hover/press/focus, invalid/required, pending, selected/mixed and disabled states. Measure rendered text, outlines and state indicators against adjacent/composited backgrounds, especially Glass gradients. Record sizes, ratios and any criterion exception; keep non-color cues. |
80
+ | V2 — resizing | Test native browser zoom at 200% text resize and a 1280 CSS px viewport at 400% zoom (320 CSS px effective width), plus actual narrow viewports. Apply the text-spacing overrides below together. Check clipping, two-axis scrolling, modal scrolling, sticky/overlay focus obstruction and portrait/landscape. A resized viewport alone is not browser-zoom evidence. |
81
+ | V3 — preferences | Enable real OS reduced motion and, on Windows, contrast themes/forced colors. Verify visible focus, selected/disabled/mixed marks, pending feedback and readable controls after decorative paint disappears. Label browser-emulated media checks as emulation; they do not establish real OS or AT behavior. |
82
+ | T1 — mobile AT | On iOS/Android, explore by touch and swipe reading order, use heading/link/form navigation, activate with double-tap, edit and dismiss the on-screen keyboard, select options and submit/correct/reset the form. Open/close Dialog and verify touch/reading containment and restoration. Ensure collapsed/disabled/background items are treated appropriately. Measure the real label/control hit area and spacing, not only its glyph. |
83
+
84
+ Native radio reverse-entry behavior can differ between browsers when no option
85
+ is checked; record the behavior instead of forcing the ARIA example's focus
86
+ model. [APG radio guidance](https://www.w3.org/WAI/ARIA/apg/patterns/radio/).
87
+ Use the [modal Dialog guidance](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)
88
+ for content-dependent initial focus and restoration. APG is informative guidance;
89
+ its examples do not certify a library's browser/AT compatibility.
90
+
91
+ ### Operating the required AT pairs
92
+
93
+ | Pair | Procedure and primary reference |
94
+ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
95
+ | NVDA + Firefox / Windows | Record NVDA's installed version and browse/focus settings. Use `NVDA+Space` to switch browse/focus modes; Tab/Shift+Tab also exercise native focus. Browse with heading/link/form/button/checkbox/radio commands and test actual input in focus mode. Capture the relevant Speech Viewer output alongside focus observations. [NVDA browse mode](https://download.nvaccess.org/documentation/userGuide.html#BrowseMode), [Speech Viewer](https://download.nvaccess.org/documentation/userGuide.html#SpeechViewer). |
96
+ | VoiceOver + Safari / macOS | Record Safari, OS/build, VoiceOver modifier and Safari/macOS keyboard navigation settings. Use `VO+Left/Right` to read, `VO+Space` to activate, and `VO+Shift+Down/Up` to enter/exit groups; use the rotor for headings/links/forms. Test plain Tab order as a separate observation. [Apple VoiceOver guide](https://support.apple.com/guide/voiceover/vo4be8816d70/mac), [rotor](https://support.apple.com/guide/voiceover/mchlp2719/mac). |
97
+ | VoiceOver + Safari / iOS | Record device, iOS build, Safari context and VoiceOver settings. Touch explores; swipe Right/Left moves next/previous; double-tap activates. Use the rotor's headings/links/form-control categories and check the on-screen keyboard and modal boundaries. [Apple gestures](https://support.apple.com/guide/iphone/iph3e2e2281/ios), [Safari](https://support.apple.com/guide/iphone/iphe4ee74be8/ios). |
98
+ | TalkBack + Chrome / Android | Record Android/build, device, Chrome and installed TalkBack version/settings. Touch explores; swipe Right/Left moves next/previous; double-tap activates; two-finger swipe scrolls. Use reading controls for headings/links/controls, accounting for customised gestures. [Google Chrome guidance](https://support.google.com/accessibility/android/answer/2633135?hl=en), [TalkBack gestures](https://support.google.com/accessibility/android/answer/6151827?hl=en). |
99
+
100
+ ## WCAG evidence map
101
+
102
+ These are relevant requirements to assess, not passed criterion cells. Each run
103
+ records applicability and an observed outcome for the criteria it covers. Follow
104
+ the linked definitions/exception rules; the list is not a complete product audit.
105
+
106
+ | Scenario / requirement area | Relevant A/AA criteria and evidence |
107
+ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
108
+ | K1–K5, T1: semantics and content | [1.1.1 A](https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html), [1.3.1 A](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html), [1.3.2 A](https://www.w3.org/WAI/WCAG22/Understanding/meaningful-sequence.html), [2.4.4 A](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html), [2.4.6 AA](https://www.w3.org/WAI/WCAG22/Understanding/headings-and-labels.html), [2.5.3 A](https://www.w3.org/WAI/WCAG22/Understanding/label-in-name.html), [3.3.2 A](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions.html), [4.1.2 A](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html): capture reading order, accessible names, grouping, roles/states and meaningful instructions. |
109
+ | K1–K5: keyboard and focus | [2.1.1 A](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html), [2.1.2 A](https://www.w3.org/WAI/WCAG22/Understanding/no-keyboard-trap.html), [2.4.3 A](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html), [2.4.7 AA](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html), [2.4.11 AA](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum.html): record the key sequence, focus order, visible indicator, exit and overlay/scroll behavior. |
110
+ | K2/K5: input, errors and feedback | [1.3.5 AA](https://www.w3.org/WAI/WCAG22/Understanding/identify-input-purpose.html), [3.2.1 A](https://www.w3.org/WAI/WCAG22/Understanding/on-focus.html), [3.2.2 A](https://www.w3.org/WAI/WCAG22/Understanding/on-input.html), [3.3.1 A](https://www.w3.org/WAI/WCAG22/Understanding/error-identification.html), [3.3.3 AA](https://www.w3.org/WAI/WCAG22/Understanding/error-suggestion.html), [4.1.3 AA](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html): record purpose metadata where applicable, context changes, error/correction text and actual status announcements without focus theft. Opening a dialog is not itself a status message. |
111
+ | V1: visual information | [1.4.1 A](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html), [1.4.3 AA](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html), [1.4.11 AA](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html): record non-color cues and measured contrast on actual backgrounds. Normal text needs 4.5:1; large text needs 3:1; required control/state visual information needs 3:1 against adjacent colors. |
112
+ | V2/T1: adaptable layout | [1.3.4 AA](https://www.w3.org/WAI/WCAG22/Understanding/orientation.html), [1.4.4 AA](https://www.w3.org/WAI/WCAG22/Understanding/resize-text.html), [1.4.10 AA](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html), [1.4.12 AA](https://www.w3.org/WAI/WCAG22/Understanding/text-spacing.html): retain content/function at the tested zoom, effective width, spacing and orientation; record any applicable exceptions. |
113
+ | K1/T1: pointer and targets | [2.5.2 A](https://www.w3.org/WAI/WCAG22/Understanding/pointer-cancellation.html), [2.5.8 AA](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html): record cancellation behavior and measured target/spacing, or the precise exception used. |
114
+ | Additional hover/focus content | [1.4.13 AA](https://www.w3.org/WAI/WCAG22/Understanding/content-on-hover-or-focus.html): if extra content appears, check dismissal, hoverability and persistence; an ordinary paint-only hover effect is not extra content. |
115
+
116
+ Keep these distinctions explicit:
117
+
118
+ - **Focus:** 2.4.7 and 2.4.11 are AA. Minimum non-obscuring forbids total coverage
119
+ by author content. The stronger two-pixel-perimeter rule in
120
+ [2.4.13 Focus Appearance](https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html)
121
+ is AAA, not an AA minimum.
122
+ - **Targets:** 2.5.8's AA minimum is 24×24 CSS px unless a specified exception
123
+ applies. For its spacing exception, centre a 24px-diameter circle on each
124
+ undersized target's bounding box: it must intersect neither another target
125
+ nor another undersized target's circle. Other exceptions are an equivalent
126
+ conforming control on the same page, inline text constraints, unmodified
127
+ user-agent sizing, and essential/legally required presentation. Styled native
128
+ controls are not automatically exempt. Record the chosen exception and geometry.
129
+ - **Contrast:** large text is at least 18pt, or 14pt bold. Apply the criterion's
130
+ inactive/decorative/logotype and unmodified-UA exceptions where applicable;
131
+ record disabled legibility as usability evidence even when exempt.
132
+ - **Spacing:** test line height 1.5×font size, paragraph spacing 2×font size,
133
+ letter spacing 0.12×font size and word spacing 0.16×font size together, with
134
+ applicable language/script exceptions. These are resilience tests, not required
135
+ default typography settings.
136
+ - **Preferences:** forced-colors and reduced-motion checks are part of Radiant's
137
+ functional CSS target. An emulated preference or a `motion-reduce` class proves
138
+ neither an OS/AT result nor complete WCAG conformance.
139
+
140
+ ## Record and retain evidence
141
+
142
+ `pnpm test:browser` first writes `output/browser/environment.json` from the
143
+ installed Chromium and host OS, then runs the existing tests. Preflight clears
144
+ prior environment/JUnit files first so an interrupted run cannot reuse an old
145
+ pass. Preserve an old run before starting the next. The receipt contains
146
+ exact browser/Node/Playwright/Vitest versions, OS/build details, revision, dirty
147
+ flag and CI run link. AT is explicitly `not-run`. It is environment metadata,
148
+ not a passing test result: pair it with the completed `junit.xml`, actual project/
149
+ case selection, logs and manual evidence. A failed or interrupted suite does not
150
+ inherit a prior pass from the receipt. The current command runs Chromium only.
151
+
152
+ CI uploads these files as **browser-results** with a 14-day retention period.
153
+ Before they expire, retain the version/result summary and relevant captures in a
154
+ reviewed `docs/verification/YYYY-MM-DD-<scope>.md` record or durable issue/PR
155
+ attachments. Link the exact CI run and commit; keep older records immutable and
156
+ append a new verification when code, browser/AT, OS, theme or adapter changes.
157
+ A preview/run of the environment recorder alone has no test-result status.
158
+
159
+ Use this structure for each actual manual or automated run:
160
+
161
+ ```text
162
+ Record ID, date/time, tester and method (manual / automated / emulated)
163
+ Source revision + dirty changes, package integrity/fixture, CSS/reset/fonts
164
+ OS/version/build, device, browser/version, AT/version (or bundled OS build)
165
+ AT mode/verbosity/custom gestures, keyboard/zoom/scaling/viewport/orientation
166
+ Preset/mode and state; scenario IDs; applicable WCAG criteria or N/A reason
167
+ Steps + expected outcome + observed outcome / actual announcement / ratio / geometry
168
+ Result per case: pass / fail / not-run / incomplete / not-applicable (with reason)
169
+ JUnit/log/capture/transcript links; defect issue + affected combinations
170
+ Retest revision and result; remaining untested combinations/criterion gaps
171
+ ```
172
+
173
+ A failure gets a reproducible issue and an affected-combination list; link its
174
+ fix and retest instead of erasing it. An inconclusive axe result stays incomplete
175
+ until reviewed. Never turn a missing manual result into pass, N/A or "supported".
176
+ Publishing this process can complete DEV-47 while the manual matrix remains open;
177
+ those gaps continue into DEV-134/DEV-83's readiness decisions.
178
+
179
+ ## Consumer responsibilities
180
+
181
+ Radiant supplies native semantics, relationships and functional styling. Product
182
+ owners provide meaningful names/headings/content, valid form instructions and
183
+ errors, appropriate initial focus, sensible navigation, validation/persistence,
184
+ font assets and theme/adapter choices. They must verify their rendered colors,
185
+ content, responsive layouts, complete tasks and any overrides/host replacements.
186
+ Page language/titles, consistent navigation, authentication, data-entry/error
187
+ prevention and other page/process criteria also need product-level applicability
188
+ and evidence. Neither a passing library matrix nor a paid certificate replaces
189
+ that evaluation. Follow the [system guide](system.md) when composing the controls.
package/docs/system.md ADDED
@@ -0,0 +1,218 @@
1
+ # Radiant system guide
2
+
3
+ Use this guide to theme, compose and customise the ten families in the current
4
+ source: Button, Link, Field, Input, Checkbox, RadioGroup (including Radio),
5
+ Dialog, Collapsible, Accordion and Card. Their public props and types are in the
6
+ [README](../README.md) and package declarations. Changes under
7
+ [Unreleased](../CHANGELOG.md#unreleased) require a release before npm consumers
8
+ can use them; keep JavaScript and CSS on the same version. Radiant remains
9
+ experimental during 0.x.
10
+
11
+ ## Compose by responsibility
12
+
13
+ Use Button for actions and Link for navigation, including when a Link looks
14
+ like a button. Use Field for label/help/error relationships, and native controls
15
+ for values and selection. Card groups content; Dialog owns open state and its
16
+ native modal lifecycle; Collapsible owns a disclosure; Accordion composes
17
+ Collapsible for a selection of sections.
18
+
19
+ DialogTrigger and DialogClose compose Button in both default and replacement
20
+ paths. They accept Button's presentation and `render` interface. RadioGroup
21
+ composes Field. Action-shaped Link shares Button's presentation while retaining
22
+ an anchor. Reuse these families when assembling an interface so their theme,
23
+ keyboard behavior and relationships travel together.
24
+
25
+ Action presentation uses three independent choices:
26
+
27
+ | Prop | Values | Default |
28
+ | ------------- | ------------------------------------------------------------------------- | ----------------------------- |
29
+ | `variant` | `solid`, `soft`, `outline`, `ghost`; Link also accepts `inline`, `subtle` | Button `solid`; Link `inline` |
30
+ | `tone` | `accent`, `neutral`, `warning`, `danger` | `accent` |
31
+ | `controlSize` | `small`, `medium`, `large` | `medium` |
32
+
33
+ Input, Checkbox, Radio and RadioGroup share `controlSize`. Input's numeric native
34
+ `size` still measures character width. A variant selects treatment; a tone
35
+ selects its semantic palette.
36
+
37
+ ## Set up styles and themes
38
+
39
+ Choose one CSS route: import `@cognitap/radiant/styles.css` once for compiled
40
+ styles, or import `@cognitap/radiant/tailwind.css` alongside your application's
41
+ Tailwind entry. The reset is a separate opt-in import. Compiled CSS supplies a
42
+ neutral light/dark baseline without a provider. Follow the
43
+ [setup examples](../README.md#usage) and [Tailwind route](../README.md#with-tailwind).
44
+
45
+ Author a theme with `defineTheme({ id, name, tokens, components, modes })`.
46
+ It validates typed partial definitions and resolves immutable light/dark maps.
47
+ Choose a built-in preset from the readonly `themes` registry by stable `id`, or
48
+ use its named export, such as `radiant`, `glass` or `defaultTheme`. Load preset
49
+ fonts in your application; choosing a theme never downloads a font. The
50
+ [theming reference](theming.md#define-and-apply-a-theme) owns the authoring
51
+ example, token defaults, preset IDs, font families/weights and migration steps.
52
+
53
+ | Token group | Shared responsibility |
54
+ | ------------ | ---------------------------------------------------------------------------------- |
55
+ | `color` | Surface, foreground, borders, focus, invalid/disabled colors and action tone pairs |
56
+ | `typography` | Body, label and heading font decisions |
57
+ | `control` | Small/medium/large metrics, control shape and borders |
58
+ | `surface` | Canvas background, panel shape, spacing, elevation and backdrop |
59
+ | `focus` | Outline width, offset and style |
60
+ | `motion` | Press/release, color and disclosure timing |
61
+ | `spacing` | Label, field, group, header and footer gaps |
62
+ | `state` | Disabled opacity |
63
+
64
+ Apply a theme with `ThemeScope`, a normal `div` whose props/ref target that
65
+ host. `mode` is independently `light`, `dark` or `system`; system follows the
66
+ browser preference through CSS. Omitted theme/mode inherit. An explicit named
67
+ theme starts afresh from library defaults, then common values, then its mode
68
+ layer. Nested `defaultTheme` resets inherited effects as well as colors.
69
+
70
+ Within a scope, precedence is **component override → shared role → neutral
71
+ baseline**. Promote a decision to `tokens` when it should affect several
72
+ families; put a deliberate exception in `components.<family>`. Button-only
73
+ fonts/effects stay action-local. `components.radioGroup.gap` spaces options;
74
+ `components.radio.labelGap` spaces an option's label. Passive surfaces use
75
+ surface roles, and Radio stays round by default.
76
+
77
+ Use `ThemeComponentOverrides` for reusable component configuration and
78
+ `ThemeStyle` for local `style` values. Public CSS variables follow their typed
79
+ paths: `tokens.control.radius` becomes `--rad-control-radius`, and
80
+ `components.input.radius` becomes `--rad-input-radius`. Local styles override
81
+ generated values on the same host; caller classes merge after defaults. Use the
82
+ Tailwind route to generate new utility classes supplied by your application.
83
+
84
+ A mode-only scope re-materialises its selected theme. Put token exceptions that
85
+ must survive it on a ThemeScope's inline `style` or in the theme definition;
86
+ intervening ordinary DOM/stylesheet overrides are not recovered automatically.
87
+ A new named theme clears inherited exceptions. See the precise
88
+ [scope and override rules](theming.md#scopes-mode-and-overrides).
89
+
90
+ ## Find the actual styling and ref target
91
+
92
+ Root `className`, `style`, native attributes and `ref` reach the documented
93
+ host. A convenience label does not move input props to its wrapper.
94
+
95
+ | Public family / parts | Host and target |
96
+ | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
97
+ | Button / Link | `button` / `a`, including through a compatible `render` adapter |
98
+ | Field | `div` in control layout; `fieldset` in group layout |
99
+ | Input / Checkbox / Radio | Native `input`; Checkbox/Radio wrapper, label and indicator use `parts` |
100
+ | RadioGroup | Field's `fieldset`; `parts.options` styles its internal option grid |
101
+ | Dialog | Logical state owner with no DOM/style/ref target |
102
+ | DialogTrigger / DialogClose | Button's `button` host |
103
+ | DialogContent / DialogTitle / DialogDescription | `dialog` / `h2` / `p` |
104
+ | Collapsible / CollapsibleTrigger / CollapsibleContent | `details` / `summary` / `div` |
105
+ | Accordion / AccordionItem / AccordionTrigger / AccordionContent | `div` / Collapsible `details` / `summary` / `div`; trigger `level` adds a heading without moving the ref |
106
+ | Card / CardHeader / CardContent / CardFooter | Passive `div` hosts |
107
+ | CardTitle / CardDescription | Heading selected by `level` / `p` |
108
+
109
+ Field exposes `parts.label`, `description`, `error` and `required`;
110
+ Checkbox/Radio expose `parts.wrapper`, `label` and `indicator`. RadioGroup adds
111
+ `parts.options` to Field's hooks. Each hook accepts only `className` and `style`.
112
+ Use the explicit compound parts for layout where a family provides them.
113
+
114
+ `data-slot` is a set of identity tokens. Select with membership, for example
115
+ `[data-slot~="dialog-trigger"]`. Composed identities retain their base:
116
+ `button dialog-trigger`, `button dialog-close`, `field radio-group`,
117
+ `collapsible accordion-item`, `collapsible-trigger accordion-trigger`, and
118
+ `collapsible-content accordion-content`. Caller identities are additive only
119
+ where the family's props support them; owned identities remain protected.
120
+
121
+ Style actual state: native `:disabled`, `:checked`, `:indeterminate` and `open`;
122
+ Button pending uses `aria-busy`; Field/RadioGroup expose presence-based
123
+ `data-invalid`, `data-disabled` and `data-required`. DialogContent and the
124
+ disclosure parts expose `data-state="open" | "closed"`. Actions expose
125
+ `data-variant`, `data-tone` and `data-control-size`; controls expose
126
+ `data-control-size` independently of native Input `size`. There is no universal
127
+ synthetic state attribute to substitute for native or ARIA state.
128
+
129
+ ## State and forms
130
+
131
+ Keep one owner per state axis for a mount. Use `value`/`checked`/`open` for
132
+ controlled state and their `default*` counterparts for initial uncontrolled
133
+ state. Accordion uses `value`/`defaultValue` and a fixed single/multiple type.
134
+ Remount to change ownership or selection type. Controlled callbacks request a
135
+ change; the consumer decides whether to accept it. No-op requests and prop
136
+ synchronisation do not create another semantic change callback.
137
+
138
+ Text changes and blur retain native event meanings. RadioGroup owns its options'
139
+ name/selection; `value={null}` clears a controlled group and `""` remains a real
140
+ option value. Choose one state-writing callback, `onValueChange` or `onChange`.
141
+ Checkbox's `checked` is boolean state; its `value` is submitted data.
142
+
143
+ Field owns IDs, label/help/error relationships and inherited metadata. Give an
144
+ explicit control ID through Field's `controlId`. Radiant controls consume those
145
+ relationships; a native adapter uses `children(controlProps)` and forwards them
146
+ to its control. Owned error/disabled/required state cannot be erased by a child.
147
+ A plain Field group preserves native fieldset/first-legend behavior and does
148
+ not make every checkbox required. RadioGroup applies its requirement to the
149
+ mutually exclusive native choice.
150
+
151
+ The consumer owns validation rules/timing, touched/dirty state, error text,
152
+ submission and persistence. Native reset restores uncontrolled controls; a
153
+ controlled adapter resets its values and validation metadata together. Form
154
+ reset does not reset Dialog or disclosure state. Dialog retains its DOM form
155
+ association; compose one form without nesting forms. TanStack is an optional
156
+ reference adapter, outside the runtime dependency and public export surface.
157
+
158
+ For cancellable activation, guards run first, the consumer handler runs next,
159
+ and the library requests a change only when `defaultPrevented` is false.
160
+ Native change/toggle/blur are observations, not vetoable requests. Preserve one
161
+ handler chain and the real host ref, including callback-ref cleanup. Public
162
+ `useField`, `useDialog`, `useCollapsible` and `useAccordion` return null outside
163
+ their owner; required parts fail clearly when misplaced. The
164
+ [React binding reference](https://github.com/cognitap/radiant/blob/main/docs/react-bindings.md)
165
+ details lifecycle, reconciliation, SSR and hydration behavior.
166
+
167
+ ## Preserve behavior when customising
168
+
169
+ Button, Link and Dialog actions support `render(resolvedNativeProps)`. Forward
170
+ all resolved props, ref and children to one compatible button or anchor;
171
+ presentation is already resolved. A router adapter keeps native modified-click,
172
+ target and download behavior. Preserve Button's resolved pending children and
173
+ guarded handler; passing them through another Button would wrap/style them
174
+ again. Field's control-prop callback adapts relationships rather than replacing
175
+ Field's host.
176
+
177
+ Keep native controls and labels operable, accessible names/description IDs
178
+ connected, and focus/invalid/disabled/pending cues visible. Closed Dialog/details
179
+ content stays mounted and hidden by the native/functional styles. Preserve
180
+ Dialog bounds, scrolling, top-layer modal focus behavior, and a direct-child
181
+ summary for details. Keep decorative indicators hidden from assistive technology.
182
+ Preserve reduced-motion alternatives and forced-colors readability when changing
183
+ paint, motion or hosts. A type-correct adapter alone does not prove these behaviors.
184
+
185
+ ## Reuse the canonical examples
186
+
187
+ Use the global Storybook **Theme** and **Mode** controls in Canvas and Docs.
188
+ Ordinary stories inherit them; **System → Theming → Comparison** is the named
189
+ preset comparison. Follow the [Storybook inspection guide](https://github.com/cognitap/radiant/blob/main/docs/storybook.md).
190
+
191
+ | Need | Canonical live source |
192
+ | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
193
+ | One labelled control and local override | [Input Default / Customisation](https://github.com/cognitap/radiant/blob/main/src/Input.stories.tsx) |
194
+ | Native form, optional TanStack owner, the same form in Card or Dialog | [ProfileExample](https://github.com/cognitap/radiant/blob/main/.storybook/examples/ProfileForm.tsx), exposed by [Recipes → Forms](https://github.com/cognitap/radiant/blob/main/src/Form.stories.tsx); choose its `placement` control |
195
+ | Assembled interface across all ten families | [WorkspaceSettings](https://github.com/cognitap/radiant/blob/main/.storybook/examples/WorkspaceSettings.tsx), exposed by [Recipes → Workspace → Settings](https://github.com/cognitap/radiant/blob/main/src/Workspace.stories.tsx) |
196
+
197
+ These are development examples using public Radiant names, not package exports.
198
+ Adapt the existing form's state owner and placement rather than copying a second
199
+ form or replacing its actions with bespoke styled hosts. Application imports
200
+ come from `@cognitap/radiant`; implementation deep imports are unsupported.
201
+
202
+ The installed composition checkpoint reuses these exact recipes with public
203
+ package imports. When copying TypeScript recipe sources into an application,
204
+ follow its local module-resolution rules: Cognitap's current Next/Turbopack
205
+ setup needs extensionless local TSX imports, whereas the NodeNext installed
206
+ fixture uses `.js` specifiers. This adaptation does not change Radiant's compiled
207
+ JavaScript imports. See the [checkpoint commands](https://github.com/cognitap/radiant/blob/main/docs/testing.md#evidence-and-readiness).
208
+ An older registry package cannot verify newer exported components; use a matching
209
+ build/archive checkpoint and keep the registry limitation explicit until release.
210
+
211
+ For a change to this contract, update its guide/reference and canonical example
212
+ together, then run the [verification gate](https://github.com/cognitap/radiant/blob/main/docs/testing.md).
213
+ Use the [browser/AT matrix](accessibility.md) for target combinations, manual
214
+ scenarios, exact-version evidence and unverified gaps.
215
+ Check relevant keyboard/form/ref behavior and actual appearance in both modes;
216
+ automated accessibility results do not establish complete visual or assistive
217
+ technology readiness. Historical design decisions and acceptance sketches remain
218
+ in the [harmonisation record](https://github.com/cognitap/radiant/blob/main/docs/contracts/README.md).