@ceed/ads 1.25.1-next.3 → 1.27.0

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)