@cognitap/radiant 0.0.6 → 0.0.8

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 (196) hide show
  1. package/CHANGELOG.md +82 -395
  2. package/README.md +41 -1014
  3. package/RELEASE_POLICY.md +3 -3
  4. package/dist/library/Accordion.d.ts +3 -0
  5. package/dist/library/Accordion.d.ts.map +1 -1
  6. package/dist/library/Accordion.js +1 -1
  7. package/dist/library/Accordion.js.map +1 -1
  8. package/dist/library/Button.d.ts +5 -0
  9. package/dist/library/Button.d.ts.map +1 -1
  10. package/dist/library/Button.js +8 -7
  11. package/dist/library/Button.js.map +1 -1
  12. package/dist/library/Card.d.ts +2 -0
  13. package/dist/library/Card.d.ts.map +1 -1
  14. package/dist/library/Card.js +1 -1
  15. package/dist/library/Card.js.map +1 -1
  16. package/dist/library/Checkbox.d.ts +5 -0
  17. package/dist/library/Checkbox.d.ts.map +1 -1
  18. package/dist/library/Checkbox.js +3 -2
  19. package/dist/library/Checkbox.js.map +1 -1
  20. package/dist/library/Collapsible.d.ts +4 -0
  21. package/dist/library/Collapsible.d.ts.map +1 -1
  22. package/dist/library/Collapsible.js +22 -4
  23. package/dist/library/Collapsible.js.map +1 -1
  24. package/dist/library/Dialog.d.ts +3 -0
  25. package/dist/library/Dialog.d.ts.map +1 -1
  26. package/dist/library/Dialog.js.map +1 -1
  27. package/dist/library/Field.d.ts +8 -0
  28. package/dist/library/Field.d.ts.map +1 -1
  29. package/dist/library/Field.js +2 -0
  30. package/dist/library/Field.js.map +1 -1
  31. package/dist/library/Input.d.ts +3 -0
  32. package/dist/library/Input.d.ts.map +1 -1
  33. package/dist/library/Input.js +1 -0
  34. package/dist/library/Input.js.map +1 -1
  35. package/dist/library/Link.d.ts +5 -0
  36. package/dist/library/Link.d.ts.map +1 -1
  37. package/dist/library/Link.js.map +1 -1
  38. package/dist/library/RadioGroup.d.ts +8 -0
  39. package/dist/library/RadioGroup.d.ts.map +1 -1
  40. package/dist/library/RadioGroup.js +4 -2
  41. package/dist/library/RadioGroup.js.map +1 -1
  42. package/dist/library/Select.d.ts +87 -0
  43. package/dist/library/Select.d.ts.map +1 -0
  44. package/dist/library/Select.js +454 -0
  45. package/dist/library/Select.js.map +1 -0
  46. package/dist/library/cn.d.ts.map +1 -1
  47. package/dist/library/cn.js +20 -3
  48. package/dist/library/cn.js.map +1 -1
  49. package/dist/library/examples/expressive.d.ts +4 -0
  50. package/dist/library/examples/expressive.d.ts.map +1 -0
  51. package/dist/library/{themes → examples}/expressive.js +4 -3
  52. package/dist/library/examples/expressive.js.map +1 -0
  53. package/dist/library/examples/glass.d.ts +4 -0
  54. package/dist/library/examples/glass.d.ts.map +1 -0
  55. package/dist/library/{themes → examples}/glass.js +9 -3
  56. package/dist/library/examples/glass.js.map +1 -0
  57. package/dist/library/examples/index.d.ts +13 -0
  58. package/dist/library/examples/index.d.ts.map +1 -0
  59. package/dist/library/examples/index.js +32 -0
  60. package/dist/library/examples/index.js.map +1 -0
  61. package/dist/library/examples/jelly.d.ts +4 -0
  62. package/dist/library/examples/jelly.d.ts.map +1 -0
  63. package/dist/library/{themes → examples}/jelly.js +4 -3
  64. package/dist/library/examples/jelly.js.map +1 -0
  65. package/dist/library/examples/preset-values.d.ts.map +1 -0
  66. package/dist/library/examples/preset-values.js.map +1 -0
  67. package/dist/library/examples/radiant.d.ts +4 -0
  68. package/dist/library/examples/radiant.d.ts.map +1 -0
  69. package/dist/library/{themes → examples}/radiant.js +4 -3
  70. package/dist/library/examples/radiant.js.map +1 -0
  71. package/dist/library/examples/sharp-3d.d.ts +4 -0
  72. package/dist/library/examples/sharp-3d.d.ts.map +1 -0
  73. package/dist/library/{themes → examples}/sharp-3d.js +4 -3
  74. package/dist/library/examples/sharp-3d.js.map +1 -0
  75. package/dist/library/examples/soft-squircle.d.ts +4 -0
  76. package/dist/library/examples/soft-squircle.d.ts.map +1 -0
  77. package/dist/library/{themes → examples}/soft-squircle.js +4 -3
  78. package/dist/library/examples/soft-squircle.js.map +1 -0
  79. package/dist/library/examples/ticket.d.ts +4 -0
  80. package/dist/library/examples/ticket.d.ts.map +1 -0
  81. package/dist/library/{themes → examples}/ticket.js +4 -3
  82. package/dist/library/examples/ticket.js.map +1 -0
  83. package/dist/library/index.d.ts +3 -1
  84. package/dist/library/index.d.ts.map +1 -1
  85. package/dist/library/index.js +2 -1
  86. package/dist/library/index.js.map +1 -1
  87. package/dist/library/internal/select.d.ts +37 -0
  88. package/dist/library/internal/select.d.ts.map +1 -0
  89. package/dist/library/internal/select.js +42 -0
  90. package/dist/library/internal/select.js.map +1 -0
  91. package/dist/library/motion/MotionLink.d.ts +1 -0
  92. package/dist/library/motion/MotionLink.d.ts.map +1 -1
  93. package/dist/library/motion/MotionLink.js +9 -10
  94. package/dist/library/motion/MotionLink.js.map +1 -1
  95. package/dist/library/motion/host.d.ts +7 -3
  96. package/dist/library/motion/host.d.ts.map +1 -1
  97. package/dist/library/motion/host.js +13 -5
  98. package/dist/library/motion/host.js.map +1 -1
  99. package/dist/library/motion/popup.d.ts +5 -0
  100. package/dist/library/motion/popup.d.ts.map +1 -0
  101. package/dist/library/motion/popup.js +60 -0
  102. package/dist/library/motion/popup.js.map +1 -0
  103. package/dist/library/motion/press.d.ts.map +1 -1
  104. package/dist/library/motion/press.js +41 -14
  105. package/dist/library/motion/press.js.map +1 -1
  106. package/dist/library/motion/pressPolicy.d.ts.map +1 -1
  107. package/dist/library/motion/pressPolicy.js +2 -2
  108. package/dist/library/motion/pressPolicy.js.map +1 -1
  109. package/dist/library/motion/react.d.ts.map +1 -1
  110. package/dist/library/motion/react.js +3 -1
  111. package/dist/library/motion/react.js.map +1 -1
  112. package/dist/library/motion/transitions.d.ts.map +1 -1
  113. package/dist/library/motion/transitions.js +48 -15
  114. package/dist/library/motion/transitions.js.map +1 -1
  115. package/dist/library/react/useControllableState.d.ts +1 -0
  116. package/dist/library/react/useControllableState.d.ts.map +1 -1
  117. package/dist/library/react/useControllableState.js +8 -1
  118. package/dist/library/react/useControllableState.js.map +1 -1
  119. package/dist/library/selectStyles.d.ts +4 -0
  120. package/dist/library/selectStyles.d.ts.map +1 -0
  121. package/dist/library/selectStyles.js +32 -0
  122. package/dist/library/selectStyles.js.map +1 -0
  123. package/dist/library/styles.css +1 -1
  124. package/dist/library/themes/components.d.ts +24 -0
  125. package/dist/library/themes/components.d.ts.map +1 -1
  126. package/dist/library/themes/components.js +24 -0
  127. package/dist/library/themes/components.js.map +1 -1
  128. package/dist/library/themes/index.d.ts +1 -11
  129. package/dist/library/themes/index.d.ts.map +1 -1
  130. package/dist/library/themes/index.js +1 -19
  131. package/dist/library/themes/index.js.map +1 -1
  132. package/docs/accessibility.md +76 -142
  133. package/docs/architecture.md +208 -0
  134. package/docs/motion.md +115 -396
  135. package/docs/theming.md +275 -882
  136. package/package.json +9 -5
  137. package/src/Accordion.tsx +4 -1
  138. package/src/Button.tsx +13 -7
  139. package/src/Card.tsx +3 -1
  140. package/src/Checkbox.tsx +7 -2
  141. package/src/Collapsible.tsx +28 -4
  142. package/src/Dialog.tsx +3 -0
  143. package/src/Field.tsx +8 -0
  144. package/src/Input.tsx +3 -0
  145. package/src/Link.tsx +5 -0
  146. package/src/RadioGroup.tsx +10 -2
  147. package/src/Select.tsx +781 -0
  148. package/src/cn.ts +20 -3
  149. package/src/{themes → examples}/expressive.ts +5 -3
  150. package/src/{themes → examples}/glass.ts +10 -3
  151. package/src/examples/index.ts +35 -0
  152. package/src/{themes → examples}/jelly.ts +5 -3
  153. package/src/{themes → examples}/radiant.ts +5 -3
  154. package/src/{themes → examples}/sharp-3d.ts +5 -3
  155. package/src/{themes → examples}/soft-squircle.ts +5 -3
  156. package/src/{themes → examples}/ticket.ts +5 -3
  157. package/src/index.ts +28 -13
  158. package/src/internal/select.ts +80 -0
  159. package/src/motion/MotionLink.tsx +16 -11
  160. package/src/motion/host.ts +16 -7
  161. package/src/motion/popup.ts +55 -0
  162. package/src/motion/press.ts +32 -12
  163. package/src/motion/pressPolicy.ts +4 -2
  164. package/src/motion/react.ts +3 -1
  165. package/src/motion/transitions.ts +45 -14
  166. package/src/react/useControllableState.ts +7 -1
  167. package/src/selectStyles.ts +34 -0
  168. package/src/themes/components.ts +24 -0
  169. package/src/themes/index.ts +1 -22
  170. package/dist/library/themes/expressive.d.ts +0 -2
  171. package/dist/library/themes/expressive.d.ts.map +0 -1
  172. package/dist/library/themes/expressive.js.map +0 -1
  173. package/dist/library/themes/glass.d.ts +0 -2
  174. package/dist/library/themes/glass.d.ts.map +0 -1
  175. package/dist/library/themes/glass.js.map +0 -1
  176. package/dist/library/themes/jelly.d.ts +0 -2
  177. package/dist/library/themes/jelly.d.ts.map +0 -1
  178. package/dist/library/themes/jelly.js.map +0 -1
  179. package/dist/library/themes/preset-values.d.ts.map +0 -1
  180. package/dist/library/themes/preset-values.js.map +0 -1
  181. package/dist/library/themes/radiant.d.ts +0 -2
  182. package/dist/library/themes/radiant.d.ts.map +0 -1
  183. package/dist/library/themes/radiant.js.map +0 -1
  184. package/dist/library/themes/sharp-3d.d.ts +0 -2
  185. package/dist/library/themes/sharp-3d.d.ts.map +0 -1
  186. package/dist/library/themes/sharp-3d.js.map +0 -1
  187. package/dist/library/themes/soft-squircle.d.ts +0 -2
  188. package/dist/library/themes/soft-squircle.d.ts.map +0 -1
  189. package/dist/library/themes/soft-squircle.js.map +0 -1
  190. package/dist/library/themes/ticket.d.ts +0 -2
  191. package/dist/library/themes/ticket.d.ts.map +0 -1
  192. package/dist/library/themes/ticket.js.map +0 -1
  193. package/docs/system.md +0 -264
  194. /package/dist/library/{themes → examples}/preset-values.d.ts +0 -0
  195. /package/dist/library/{themes → examples}/preset-values.js +0 -0
  196. /package/src/{themes → examples}/preset-values.ts +0 -0
@@ -1,18 +1,8 @@
1
- import { radiant } from './radiant.js';
2
- import { defaultTheme } from './default.js';
3
- import { soft } from './soft-squircle.js';
4
- import { expressive } from './expressive.js';
5
- import { glass } from './glass.js';
6
- import { sharp } from './sharp-3d.js';
7
- import { jelly } from './jelly.js';
8
- import { ticket } from './ticket.js';
9
- import type { Theme } from './types.js';
10
1
  export type { SharedTokens, Theme, ThemeComponentOverrides, ThemeDefinition, ThemeLayer, ThemeMode, ThemeStyle, ThemeTokens } from './types.js';
11
2
  export { defineTheme } from './defineTheme.js';
12
3
  export { updateThemeAppearance } from './updateThemeAppearance.js';
13
4
  export type { ThemeAppearanceSettings, ThemeGeometrySettings } from './updateThemeAppearance.js';
14
- export { radiant, defaultTheme, soft, expressive, glass, sharp, jelly, ticket };
15
- export declare const themes: readonly Theme[];
5
+ export { defaultTheme } from './default.js';
16
6
  export { defineThemeDocument, parseThemeDocument, compileThemeDocument, updateThemeDocument, exportThemeSections, themeDocumentFromDefinition } from './themeDocument.js';
17
7
  export type { ThemeDocument, ThemeSectionExport, ThemeSections, ThemeSectionName, ThemeSection, ThemeColorSection, ThemeColorStop, ThemeBrandSource, ThemePalette, ThemeMotionSection, ThemeTypographySection, ThemeFontAxis, ThemeFontMetadata } from './themeDocument.js';
18
8
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/themes/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAC3C,OAAO,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAA;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAEvC,YAAY,EACV,YAAY,EACZ,KAAK,EACL,uBAAuB,EACvB,eAAe,EACf,UAAU,EACV,SAAS,EACT,UAAU,EACV,WAAW,EACZ,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA;AAClE,YAAY,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA;AAChG,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAA;AAE/E,eAAO,MAAM,MAAM,EAAE,SAAS,KAAK,EASjC,CAAA;AAEF,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,2BAA2B,EAC5B,MAAM,oBAAoB,CAAA;AAC3B,YAAY,EACV,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,sBAAsB,EACtB,aAAa,EACb,iBAAiB,EAClB,MAAM,oBAAoB,CAAA"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/themes/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,YAAY,EACZ,KAAK,EACL,uBAAuB,EACvB,eAAe,EACf,UAAU,EACV,SAAS,EACT,UAAU,EACV,WAAW,EACZ,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA;AAClE,YAAY,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA;AAChG,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAE3C,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,2BAA2B,EAC5B,MAAM,oBAAoB,CAAA;AAC3B,YAAY,EACV,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,sBAAsB,EACtB,aAAa,EACb,iBAAiB,EAClB,MAAM,oBAAoB,CAAA"}
@@ -1,23 +1,5 @@
1
- import { radiant } from './radiant.js';
2
- import { defaultTheme } from './default.js';
3
- import { soft } from './soft-squircle.js';
4
- import { expressive } from './expressive.js';
5
- import { glass } from './glass.js';
6
- import { sharp } from './sharp-3d.js';
7
- import { jelly } from './jelly.js';
8
- import { ticket } from './ticket.js';
9
1
  export { defineTheme } from './defineTheme.js';
10
2
  export { updateThemeAppearance } from './updateThemeAppearance.js';
11
- export { radiant, defaultTheme, soft, expressive, glass, sharp, jelly, ticket };
12
- export const themes = Object.freeze([
13
- radiant,
14
- defaultTheme,
15
- soft,
16
- expressive,
17
- glass,
18
- sharp,
19
- jelly,
20
- ticket
21
- ]);
3
+ export { defaultTheme } from './default.js';
22
4
  export { defineThemeDocument, parseThemeDocument, compileThemeDocument, updateThemeDocument, exportThemeSections, themeDocumentFromDefinition } from './themeDocument.js';
23
5
  //# sourceMappingURL=index.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/themes/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAC3C,OAAO,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAA;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAapC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA;AAElE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAA;AAE/E,MAAM,CAAC,MAAM,MAAM,GAAqB,MAAM,CAAC,MAAM,CAAC;IACpD,OAAO;IACP,YAAY;IACZ,IAAI;IACJ,UAAU;IACV,KAAK;IACL,KAAK;IACL,KAAK;IACL,MAAM;CACP,CAAC,CAAA;AAEF,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,2BAA2B,EAC5B,MAAM,oBAAoB,CAAA","sourcesContent":["import { radiant } from './radiant.js'\nimport { defaultTheme } from './default.js'\nimport { soft } from './soft-squircle.js'\nimport { expressive } from './expressive.js'\nimport { glass } from './glass.js'\nimport { sharp } from './sharp-3d.js'\nimport { jelly } from './jelly.js'\nimport { ticket } from './ticket.js'\nimport type { Theme } from './types.js'\n\nexport type {\n SharedTokens,\n Theme,\n ThemeComponentOverrides,\n ThemeDefinition,\n ThemeLayer,\n ThemeMode,\n ThemeStyle,\n ThemeTokens\n} from './types.js'\nexport { defineTheme } from './defineTheme.js'\nexport { updateThemeAppearance } from './updateThemeAppearance.js'\nexport type { ThemeAppearanceSettings, ThemeGeometrySettings } from './updateThemeAppearance.js'\nexport { radiant, defaultTheme, soft, expressive, glass, sharp, jelly, ticket }\n\nexport const themes: readonly Theme[] = Object.freeze([\n radiant,\n defaultTheme,\n soft,\n expressive,\n glass,\n sharp,\n jelly,\n ticket\n])\n\nexport {\n defineThemeDocument,\n parseThemeDocument,\n compileThemeDocument,\n updateThemeDocument,\n exportThemeSections,\n themeDocumentFromDefinition\n} from './themeDocument.js'\nexport type {\n ThemeDocument,\n ThemeSectionExport,\n ThemeSections,\n ThemeSectionName,\n ThemeSection,\n ThemeColorSection,\n ThemeColorStop,\n ThemeBrandSource,\n ThemePalette,\n ThemeMotionSection,\n ThemeTypographySection,\n ThemeFontAxis,\n ThemeFontMetadata\n} from './themeDocument.js'\n"]}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/themes/index.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA;AAElE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAE3C,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,2BAA2B,EAC5B,MAAM,oBAAoB,CAAA","sourcesContent":["export type {\n SharedTokens,\n Theme,\n ThemeComponentOverrides,\n ThemeDefinition,\n ThemeLayer,\n ThemeMode,\n ThemeStyle,\n ThemeTokens\n} from './types.js'\nexport { defineTheme } from './defineTheme.js'\nexport { updateThemeAppearance } from './updateThemeAppearance.js'\nexport type { ThemeAppearanceSettings, ThemeGeometrySettings } from './updateThemeAppearance.js'\nexport { defaultTheme } from './default.js'\n\nexport {\n defineThemeDocument,\n parseThemeDocument,\n compileThemeDocument,\n updateThemeDocument,\n exportThemeSections,\n themeDocumentFromDefinition\n} from './themeDocument.js'\nexport type {\n ThemeDocument,\n ThemeSectionExport,\n ThemeSections,\n ThemeSectionName,\n ThemeSection,\n ThemeColorSection,\n ThemeColorStop,\n ThemeBrandSource,\n ThemePalette,\n ThemeMotionSection,\n ThemeTypographySection,\n ThemeFontAxis,\n ThemeFontMetadata\n} from './themeDocument.js'\n"]}
@@ -1,73 +1,45 @@
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.
1
+ # Accessibility
2
+
3
+ What to check by hand, on which browsers and screen readers, and how to record
4
+ it. Automated tests are described in [testing](testing.md). The reference is
5
+ [WCAG 2.2 A/AA](https://www.w3.org/TR/WCAG22/). Component checks are evidence
6
+ toward it, but conformance applies to whole pages, so this is not a
7
+ certification.
8
+
9
+ ## Targets
10
+
11
+ | Target | Input / AT | Status |
12
+ | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
13
+ | Pinned Playwright Chromium on the local macOS host | Automated browser input and axe; no AT | Version-complete environment captured |
14
+ | 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 |
15
+ | Windows + Firefox | Keyboard and NVDA | **Not run**; browser, OS and NVDA versions unrecorded |
16
+ | macOS + Safari | Keyboard and VoiceOver | **Not run**; installed OS availability is not a test result |
17
+ | 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 |
18
+ | Android + Chrome on a physical device | Touch exploration and TalkBack; external keyboard when claimed | **Not run**; device, OS/build, Chrome and TalkBack versions unrecorded |
19
+ | 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** |
20
+
21
+ A row marked **Not run** is a gap, not a failure. Record exact versions when you
22
+ test; "latest" is not a version. Playwright WebKit does not stand in for Safari
23
+ with VoiceOver, and a desktop engine does not stand in for a mobile browser.
24
+
25
+ ## Prepare a run
26
+
27
+ 1. Use a fixed commit with matching JavaScript and CSS. Note the CSS route,
28
+ reset, overrides and fonts.
29
+ 2. Open the [canonical examples](architecture.md#examples-and-type-fixtures).
30
+ Cover native and TanStack forms, standalone, Card and Dialog placement, and
31
+ both default and `render` actions.
32
+ 3. Pick the theme and mode in the Storybook toolbar. Add `embed=true` to the
33
+ iframe URL so plays do not interfere. See
34
+ [Storybook](storybook.md#verification).
35
+ 4. Record each preset and mode you test. Never write "all themes" from a sample.
36
+ 5. Record OS, browser and screen reader versions and settings first: zoom,
37
+ viewport, text scaling, reduced motion and contrast settings.
38
+
39
+ ## Scenarios
40
+
41
+ Run keyboard cases with the screen reader off, then on. Record what is conveyed
42
+ (names, roles, states), not exact wording.
71
43
 
72
44
  | ID | Action and expected observation |
73
45
  | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -81,14 +53,12 @@ not results for Radiant.
81
53
  | 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
54
  | 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
55
 
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.
56
+ Native radio entry with no option checked differs between browsers; record it
57
+ rather than forcing the [APG radio](https://www.w3.org/WAI/ARIA/apg/patterns/radio/)
58
+ model. Use the [APG modal dialog](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)
59
+ guidance for initial focus and restoration.
90
60
 
91
- ### Operating the required AT pairs
61
+ ### Screen reader pairs
92
62
 
93
63
  | Pair | Procedure and primary reference |
94
64
  | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -97,11 +67,9 @@ its examples do not certify a library's browser/AT compatibility.
97
67
  | 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
68
  | 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
69
 
100
- ## WCAG evidence map
70
+ ## WCAG criteria
101
71
 
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.
72
+ These are the criteria to assess for each scenario, not passed results.
105
73
 
106
74
  | Scenario / requirement area | Relevant A/AA criteria and evidence |
107
75
  | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -113,50 +81,23 @@ the linked definitions/exception rules; the list is not a complete product audit
113
81
  | 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
82
  | 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
83
 
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:
84
+ Easy to get wrong:
85
+
86
+ - **Focus:** 2.4.7 and 2.4.11 are AA. The two-pixel perimeter rule (2.4.13) is
87
+ AAA.
88
+ - **Targets:** 2.5.8 needs 24×24 CSS px unless an exception applies. For the
89
+ spacing exception, a 24px circle centered on each small target must not touch
90
+ another target or circle. Styled native controls are not exempt by default.
91
+ - **Contrast:** large text is 18pt, or 14pt bold. Disabled controls are exempt,
92
+ but record their legibility anyway.
93
+ - **Text spacing:** apply line height 1.5×, paragraph spacing 2×, letter spacing
94
+ 0.12× and word spacing 0.16× the font size together.
95
+ - **Preferences:** emulated reduced motion or forced colors is not an OS result.
96
+
97
+ ## Record results
98
+
99
+ Put the results in the pull request with a link to the CI run and commit. Use
100
+ this structure for each run:
160
101
 
161
102
  ```text
162
103
  Record ID, date/time, tester and method (manual / automated / emulated)
@@ -170,20 +111,13 @@ JUnit/log/capture/transcript links; defect issue + affected combinations
170
111
  Retest revision and result; remaining untested combinations/criterion gaps
171
112
  ```
172
113
 
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.
114
+ A failure gets an issue listing the affected combinations; link the fix and
115
+ the retest. An inconclusive axe result stays incomplete until reviewed. Never
116
+ turn a missing result into a pass.
117
+
118
+ ## What the application owns
119
+
120
+ Radiant supplies native semantics, relationships and functional styles. The
121
+ application supplies meaningful names, headings and content, form instructions
122
+ and errors, initial focus, navigation, and its own colors and overrides. It must
123
+ test its own pages and tasks; a passing library matrix does not cover them.
@@ -0,0 +1,208 @@
1
+ # Architecture
2
+
3
+ How Radiant's eleven families fit together and why. Props are on the
4
+ [docs site](https://github.com/cognitap/radiant-docs); themes are in [theming](theming.md); springs are in
5
+ [motion](motion.md).
6
+
7
+ The families are Button, Link, Field, Input, Select, Checkbox, RadioGroup (with Radio),
8
+ Dialog, Collapsible, Accordion and Card. All ship in one package,
9
+ `@cognitap/radiant`. Deep imports are unsupported.
10
+
11
+ ## Native first
12
+
13
+ Each piece of behavior has one owner:
14
+
15
+ | Responsibility | Owner |
16
+ | ------------------------------------------------------ | ----------------------------------------------- |
17
+ | Activation, radio grouping, disclosure, modal dialog | The native element |
18
+ | Selection rules, ID merging and other reusable policy | Private modules in `src/internal/`, no React |
19
+ | Rendering, context, state hooks, event and ref wiring | React bindings in `src/react/` and family roots |
20
+ | Appearance | Shared tokens and component overrides |
21
+ | Content, validation, routing, fetching and persistence | The consumer |
22
+
23
+ Why: the browser already gets keyboard, focus and form behavior right.
24
+ Radiant has no headless-library dependency. Select owns its themed listbox and
25
+ item focus, while a visually hidden native select supplies form semantics.
26
+ Its local portal uses the top layer, preserving theme inheritance and modal ancestry.
27
+
28
+ Import rules:
29
+
30
+ 1. `internal` never imports React, a binding, a family or app code.
31
+ 2. `react` imports `internal` and React, never a family.
32
+ 3. Families compose other families explicitly (Accordion uses Collapsible,
33
+ RadioGroup uses Field, Dialog actions use Button). The graph stays acyclic.
34
+ 4. Nothing touches `window`, `document` or the DOM at import time. Effects use
35
+ the owning document and clean up on unmount.
36
+ 5. Server markup matches the first client render. For example, a native dialog
37
+ opens in an effect, not during render.
38
+
39
+ Extract a shared module only when a policy really repeats.
40
+
41
+ ## Composition
42
+
43
+ Use Button for actions and Link for navigation, even when a Link looks like a
44
+ button. Field owns label, help and error relationships. Card groups content.
45
+ Dialog owns open state. Collapsible owns one disclosure, and Accordion composes
46
+ Collapsible for a set of them.
47
+
48
+ Composed families reuse the real thing: DialogTrigger and DialogClose are
49
+ Buttons, RadioGroup is a Field, and an Accordion item is a Collapsible, so
50
+ theme, keyboard behavior and relationships travel together.
51
+
52
+ ## Presentation
53
+
54
+ Actions take three independent props:
55
+
56
+ | Prop | Values | Default |
57
+ | ------------- | ------------------------------------------------------------------------- | ----------------------------- |
58
+ | `variant` | `solid`, `soft`, `outline`, `ghost`; Link also accepts `inline`, `subtle` | Button `solid`; Link `inline` |
59
+ | `tone` | `accent`, `neutral`, `warning`, `danger` | `accent` |
60
+ | `controlSize` | `small`, `medium`, `large` | `medium` |
61
+
62
+ A variant picks the treatment and a tone picks the palette. Input, Checkbox,
63
+ Radio and RadioGroup share `controlSize` but have no variants. Native meanings
64
+ win: `Input.size` stays a character count, and a checkbox `value` stays its
65
+ submitted data. Radius is a theme decision, not a prop.
66
+
67
+ Button defaults to `type="button"`. `pending` blocks activation but keeps focus
68
+ and the accessible name. Link is always an anchor and has no fake `disabled`.
69
+
70
+ ## Themes
71
+
72
+ A theme is one typed `defineTheme({ id, name, tokens, components, modes })`
73
+ definition. Values resolve as **component override → shared token → neutral
74
+ baseline**, and never fall back through another family's override. Why: a
75
+ change to shared tokens should reach every family, and an exception should stay
76
+ local. A Button-only font does not become body text.
77
+
78
+ The core entry ships only the neutral baseline, `defaultTheme`. Styled presets
79
+ are examples at `@cognitap/radiant/examples`, and Storybook, the docs and the
80
+ theme workshop all read that one copy. Why: a preset is a starting point to copy
81
+ or edit, not a contract the library has to keep stable.
82
+
83
+ `ThemeScope` is a plain `div` that applies a theme to its subtree. It does not
84
+ touch the document or persist anything. Without `theme` or `mode` it inherits.
85
+ A named theme starts fresh from the library defaults, so a nested `default`
86
+ really resets an outer theme. `mode` (`light`, `dark` or `system`) is
87
+ independent of the theme, and `system` uses CSS media queries so server markup
88
+ stays stable. Token names, CSS variables, scopes and presets are in
89
+ [theming](theming.md).
90
+
91
+ ## Hosts and targeting
92
+
93
+ Root `className`, `style`, native props and `ref` always reach the documented
94
+ host, never a wrapper:
95
+
96
+ | Family or part | Host |
97
+ | --------------------------------------------------------------- | --------------------------------------------------- |
98
+ | Button / Link | `button` / `a`, including through `render` |
99
+ | Field | `div` in control layout; `fieldset` in group layout |
100
+ | Input / Checkbox / Radio | Native `input` |
101
+ | Select / SelectPortal | None; state / portal |
102
+ | SelectTrigger / SelectContent / SelectViewport / SelectItem | Button's `button` / `div` / `div` / `div` |
103
+ | RadioGroup | Field's `fieldset` |
104
+ | Dialog | None; it only owns state |
105
+ | DialogTrigger / DialogClose | Button's `button` |
106
+ | DialogContent / DialogTitle / DialogDescription | `dialog` / `h2` / `p` |
107
+ | Collapsible / CollapsibleTrigger / CollapsibleContent | `details` / `summary` / `div` |
108
+ | Accordion / AccordionItem / AccordionTrigger / AccordionContent | `div` / `details` / `summary` / `div` |
109
+ | Card / CardHeader / CardContent / CardFooter | `div` |
110
+ | CardTitle / CardDescription | Heading chosen by `level` / `p` |
111
+
112
+ Internal parts take `className` and `style` through a `parts` map. Field has
113
+ `label`, `description`, `error` and `required`. Checkbox and Radio have
114
+ `wrapper`, `label` and `indicator`, and RadioGroup adds `options`. These hooks
115
+ cannot replace IDs, ARIA, handlers or refs. Caller classes merge after the
116
+ defaults and caller `style` wins. Identity and presentation data attributes
117
+ cannot be overridden.
118
+
119
+ `data-slot` is a space-separated set, so select with `~=`, as in
120
+ `[data-slot~="button"]`. Composed parts keep their base identity:
121
+ `button dialog-trigger`, `field radio-group`, `collapsible accordion-item`.
122
+ Why: styling written for Button still reaches a DialogTrigger.
123
+
124
+ Style real state: native `:disabled`, `:checked` and `open`, plus `aria-busy`
125
+ for pending. Field and RadioGroup set `data-invalid`, `data-disabled` and
126
+ `data-required`. Disclosures and DialogContent set `data-state="open|closed"`.
127
+ Actions set `data-variant`, `data-tone` and `data-control-size`.
128
+
129
+ ## State and forms
130
+
131
+ Each state axis has one owner for the life of a mount. Pass `value`, `checked`
132
+ or `open` to control it, or `default*` to set an initial value. Passing both, or switching owner during
133
+ a mount, throws; remount with a new `key` instead. A controlled callback is a request, and the consumer
134
+ may refuse it. No-op requests and prop syncs fire no callback.
135
+
136
+ | Family | State | Callback | Empty |
137
+ | -------------------------- | ---------------------------- | -------------------------------------------- | ------- |
138
+ | Input | `value` / `defaultValue` | Native `onChange`, `onBlur` | `''` |
139
+ | Checkbox, standalone Radio | `checked` / `defaultChecked` | Native `onChange`, `onBlur` | `false` |
140
+ | RadioGroup | `value` / `defaultValue` | `onValueChange(string)` or native `onChange` | `null` |
141
+ | Select | `value` / `defaultValue` | `onValueChange(string \| null)` | `null` |
142
+ | Dialog, Collapsible | `open` / `defaultOpen` | `onOpenChange(boolean)` | `false` |
143
+ | Accordion single | `value` / `defaultValue` | `onValueChange(string \| null)` | `null` |
144
+ | Accordion multiple | `value` / `defaultValue` | `onValueChange(string[])` | `[]` |
145
+
146
+ RadioGroup owns its options' `name` and selection. Use one of `onValueChange`
147
+ or `onChange` to write state, not both. `''` is a valid option value, and `null`
148
+ clears the group.
149
+
150
+ Field owns IDs and label, help and error relationships. Set a control's ID with
151
+ Field's `controlId`. Radiant controls read Field context. A native control uses
152
+ `children(controlProps)` and forwards those props. Disabled and required only
153
+ add up: a child cannot re-enable or un-require what its Field set.
154
+
155
+ The consumer owns validation, touched and dirty state, error text, submission
156
+ and persistence. Native reset restores uncontrolled inputs. A controlled adapter
157
+ resets its own values. Reset never changes Dialog or disclosure state. Why: form
158
+ libraries differ, and Radiant should fit any of them without a hidden form
159
+ store. TanStack Form is an optional example adapter, not a dependency.
160
+
161
+ Select takes one `items` registry for SSR labels, native options and typeahead.
162
+ Rich labels supply `textValue`. The focused option and committed value are
163
+ distinct; activation commits, Escape dismisses and restores trigger focus.
164
+ Native reset silently restores uncontrolled selection. Controlled resets stay
165
+ with the owner. User selections emit form change; prop syncs do not.
166
+
167
+ ## Replacement and events
168
+
169
+ Button, Link and the Dialog actions accept `render(resolvedProps)`. Forward all
170
+ props, the ref and the children to one compatible `button` or `a`. There is no
171
+ `as` or `asChild`. Why: one convention, and the resolved props already carry
172
+ presentation, relationships and guards, so an adapter cannot drop them by
173
+ accident. Field's `children(controlProps)` adapts relationships and does not
174
+ replace Field's host.
175
+
176
+ For cancellable actions, disabled and pending guards run first, then the
177
+ consumer handler, then the state request if `defaultPrevented` is false. Native
178
+ change, toggle and blur are observations and cannot veto anything. Library and
179
+ caller refs get the same host, and callback-ref cleanup functions are honored.
180
+ `useField`, `useDialog`, `useCollapsible` and `useAccordion` read and request
181
+ state, and return `null` outside their owner. Parts that need a root throw when misplaced. Lifecycle,
182
+ SSR and hydration details are in [React bindings](react-bindings.md).
183
+
184
+ ## What customization must keep
185
+
186
+ Restyling or replacing a host is fine as long as these keep working:
187
+
188
+ - Native controls and labels stay operable, with names and descriptions connected.
189
+ - Focus, invalid, disabled and pending cues stay visible.
190
+ - Closed dialog and details content stays hidden. Dialog keeps its bounds,
191
+ scrolling and modal focus, and `details` keeps a direct-child `summary`.
192
+ - Decorative indicators stay hidden from assistive technology.
193
+ - Reduced-motion and forced-colors modes still work.
194
+
195
+ Passing the type check alone does not prove any of this. See
196
+ [accessibility](accessibility.md) for what to check by hand.
197
+
198
+ ## Examples and type fixtures
199
+
200
+ The canonical live examples are Storybook stories:
201
+ [Input](../src/Input.stories.tsx), [Recipes → Forms](../src/Form.stories.tsx)
202
+ (one form, plain or in a Card or Dialog, optionally with TanStack) and
203
+ [Recipes → Workspace → Settings](../src/Workspace.stories.tsx) (all ten
204
+ families). Change a contract and its example together.
205
+
206
+ `docs/contracts/*.ts(x)` are compile-only fixtures. `pnpm typecheck:contracts`
207
+ checks that they type-check and that contradictory props, such as `value` with
208
+ `defaultValue`, are rejected.