@ceed/ads 1.23.3 → 1.23.5

package/dist/guides/ThemeProvider.md

@@ -0,0 +1,116 @@
+# ThemeProvider
+
+## Introduction
+
+`ThemeProvider` is the root provider that supplies design tokens across ADS components.
+Internally, it applies Joy UI `CssVarsProvider` and `CssBaseline`, so the default usage is to wrap your app once at the root.
+Because this is an internal design system with pre-defined brand identity, changing tokens via `CustomTheme` is considered an anti-pattern.
+
+```tsx
+<ThemeProvider>
+  <DemoContent />
+</ThemeProvider>
+```
+
+| Field                        | Description | Default |
+| ---------------------------- | ----------- | ------- |
+| Controls resolved at runtime | —           | —       |
+
+## Usage
+
+```tsx
+import { ThemeProvider } from '@ceed/ads';
+
+function App() {
+  return (
+    <ThemeProvider>
+      <YourRoutes />
+    </ThemeProvider>
+  );
+}
+```
+
+## Why It Matters
+
+Some components may still render without the provider, but token consistency and baseline styles are not guaranteed.
+Use `ThemeProvider` at the root to ensure a consistent UI across the application.
+
+```tsx
+<Stack direction={{
+  xs: 'column',
+  md: 'row'
+}} spacing={2}>
+<Sheet variant="soft" color="success" sx={{
+  p: 1.5,
+  borderRadius: 'sm'
+}}>
+<Typography level="title-sm">Without ThemeProvider</Typography>
+</Sheet>
+<Sheet variant="soft" color="primary" sx={{
+  p: 1.5,
+  borderRadius: 'sm'
+}}>
+<Typography level="title-sm">With ThemeProvider</Typography>
+</Sheet>
+
+<Sheet variant="outlined" sx={{
+  p: 2,
+  flex: 1
+}}>
+<Typography level="title-sm">Without ThemeProvider</Typography>
+<Input label="Project Name" placeholder="Type here" sx={{
+  mt: 1.5
+}} />
+</Sheet>
+
+<ThemeProvider>
+  <Sheet variant="outlined" sx={{
+    p: 2,
+    flex: 1
+  }}>
+  <Typography level="title-sm">With ThemeProvider</Typography>
+  <Input label="Project Name" placeholder="Type here" sx={{
+    mt: 1.5
+  }} />
+</Sheet>
+</ThemeProvider>
+</Stack>
+```
+
+## Common Use Cases
+
+### App Root
+
+```tsx
+import { ThemeProvider } from '@ceed/ads';
+
+createRoot(document.getElementById('root')!).render(
+  <ThemeProvider>
+    <App />
+  </ThemeProvider>,
+);
+```
+
+### Storybook/Test Wrapper
+
+```tsx
+import { ThemeProvider } from '@ceed/ads';
+
+const renderWithTheme = (ui: React.ReactElement) => {
+  return render(<ThemeProvider>{ui}</ThemeProvider>);
+};
+```
+
+## Best Practices
+
+1. **Use a single provider at the app root**: nested providers increase maintenance complexity.
+2. **Do not create custom themes**: ADS is a standardized internal system with built-in brand identity, and `CustomTheme` usage is an anti-pattern.
+3. **Do not remove the provider**: components may drift from intended tokens and baseline styles.
+4. **Do not mix packages**: use only `@ceed/ads` ThemeProvider in ADS applications.
+
+## Accessibility
+
+1. **Check color contrast**: make sure text remains readable across component combinations.
+2. **Do not rely on color alone for state**: pair color with text and/or icons.
+3. **Keep focus visibility intact**: ensure keyboard focus rings stay clearly visible.
+4. **Maintain typography consistency**: root-level provider usage ensures predictable reading experience.

package/dist/guides/llms.txt

@@ -0,0 +1,9 @@
+# guides
+
+## Documentation
+
+- [ThemeProvider](./ThemeProvider.md)
+
+## Parent
+
+- [Parent](../llms.txt)

package/dist/llms.txt

@@ -16,8 +16,10 @@
 - [Typography](./components/data-display/Typography.md)
 - [feedback](./components/feedback/llms.txt)
 - [Alert](./components/feedback/Alert.md)
+- [CircularProgress](./components/feedback/CircularProgress.md)
 - [DialogFrame](./components/feedback/Dialog.md)
 - [Modal](./components/feedback/Modal.md)
+- [Skeleton](./components/feedback/Skeleton.md)
 - [inputs](./components/inputs/llms.txt)
 - [Autocomplete](./components/inputs/Autocomplete.md)
 - [Button](./components/inputs/Button.md)
@@ -29,14 +31,17 @@
 - [DateRangePicker](./components/inputs/DateRangePicker.md)
 - [FilterableCheckboxGroup](./components/inputs/FilterableCheckboxGroup.md)
 - [FilterMenu](./components/inputs/FilterMenu.md)
+- [FormControl](./components/inputs/FormControl.md)
 - [IconButton](./components/inputs/IconButton.md)
 - [Input](./components/inputs/Input.md)
 - [MonthPicker](./components/inputs/MonthPicker.md)
 - [MonthRangePicker](./components/inputs/MonthRangePicker.md)
 - [PercentageInput](./components/inputs/PercentageInput.md)
 - [Radio](./components/inputs/RadioButton.md)
+- [RadioList](./components/inputs/RadioList.md)
 - [RadioTileGroup](./components/inputs/RadioTileGroup.md)
 - [Select](./components/inputs/Select.md)
+- [Slider](./components/inputs/Slider.md)
 - [Switch](./components/inputs/Switch.md)
 - [Textarea](./components/inputs/Textarea.md)
 - [Uploader](./components/inputs/Uploader/llms.txt)
@@ -66,6 +71,8 @@
 - [Card](./components/surfaces/Card.md)
 - [Divider](./components/surfaces/Divider.md)
 - [Sheet](./components/surfaces/Sheet.md)
+- [guides](./guides/llms.txt)
+- [ThemeProvider](./guides/ThemeProvider.md)
 
 ## Documentation
 
@@ -74,3 +81,4 @@
 ## Children
 
 - [components](./components/llms.txt)
+- [guides](./guides/llms.txt)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ceed/ads",
-  "version": "1.23.3",
+  "version": "1.23.5",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",