@efiche/design 0.1.7 → 0.1.9

package/README.md

@@ -1,6 +1,6 @@
 # @efiche/design
 
-A pre-styled, accessible React component library. Install it, wrap your app in `ThemeProvider`, and start building.
+A pre-styled, accessible React component library. Components carry their own styles — no CSS import required.
 
 ## Installation
 
@@ -17,11 +17,10 @@ npm install @efiche/design
 
 ## Setup
 
-Import the stylesheet and wrap your app root with `ThemeProvider` **once**.
+Wrap your app root with `ThemeProvider` **once**. That's it — no stylesheet import needed.
 
 **Next.js App Router** (`app/layout.tsx`):
 ```tsx
-import '@efiche/design/styles'
 import { ThemeProvider } from '@efiche/design'
 
 export default function RootLayout({ children }: { children: React.ReactNode }) {
@@ -39,7 +38,6 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 
 **Vite / CRA** (`src/main.tsx`):
 ```tsx
-import '@efiche/design/styles'
 import { ThemeProvider } from '@efiche/design'
 import { createRoot } from 'react-dom/client'
 
@@ -50,6 +48,8 @@ createRoot(document.getElementById('root')!).render(
 )
 ```
 
+> **`ThemeProvider` is optional.** If you skip it, all components render with their built-in light-mode defaults. Add it when you need dark mode support or the `useTheme` hook.
+
 ---
 
 ## Usage
@@ -65,7 +65,7 @@ export function MyPage() {
             </CardHeader>
             <CardContent>
                 <Input placeholder="Type something..." />
-                <Button variant="solid">Submit</Button>
+                <Button>Submit</Button>
             </CardContent>
         </Card>
     )
@@ -74,6 +74,8 @@ export function MyPage() {
 
 ### Dark mode
 
+Wrap your app in `ThemeProvider` then use the `useTheme` hook anywhere inside it:
+
 ```tsx
 import { useTheme } from '@efiche/design'
 
@@ -89,6 +91,32 @@ function DarkModeToggle() {
 
 ---
 
+## How styling works
+
+Every component uses **inline styles** with CSS custom property fallbacks. For example:
+
+```
+backgroundColor: 'var(--ds-primary, #3b82f6)'
+```
+
+This means:
+- **Without `ThemeProvider`** — the hardcoded fallback (`#3b82f6`) is used. Components look correct out of the box.
+- **With `ThemeProvider`** — the `--ds-*` CSS variables are active, so dark mode and any custom theme overrides take effect.
+- **No CSS file to import.** No Tailwind, no PostCSS, no bundler config needed.
+
+### Customising the theme
+
+Override any `--ds-*` variable on `:root` (or `.ds-theme-dark` for dark mode) in your own CSS:
+
+```css
+:root {
+    --ds-primary: #6366f1;   /* change the primary colour to indigo */
+    --ds-card: #fafafa;
+}
+```
+
+---
+
 ## Components
 
 | Component | Import |
@@ -123,7 +151,7 @@ function DarkModeToggle() {
 
 ## Versioning
 
-This package follows [semantic versioning](https://semver.org). Here is how to decide which version bump to use and how to publish it.
+This package follows [semantic versioning](https://semver.org).
 
 ### Version bump rules
 
@@ -152,30 +180,26 @@ npm publish
 git push && git push --tags
 ```
 
-### What "breaking change" means for this library
-
-A **major bump** is required when consumers would need to update their code after upgrading. Examples:
+### What counts as a breaking change
 
+A **major bump** is required when consumers would need to update their code after upgrading:
 - Renaming a component (`CopyButton` → `ClipboardButton`)
-- Renaming or removing a prop (`variant="primary"` → `variant="solid"`)
+- Renaming or removing a prop
 - Changing a prop type in a non-backwards-compatible way
-- Removing a component entirely
-
-A **minor bump** is safe — consumers can upgrade without touching their code. Examples:
 
+A **minor bump** is safe — consumers can upgrade without touching their code:
 - Adding a new component
-- Adding a new optional prop to an existing component
+- Adding a new optional prop
 - Adding a new variant to `Badge`, `Button`, etc.
 
-A **patch bump** is a fix — no API changes at all. Examples:
-
+A **patch bump** is a fix — no API changes:
 - Fixing a broken style
 - Fixing a component behaviour bug
 - Updating documentation
 
 ### When to go from `0.x.x` to `1.0.0`
 
-Stay on `0.x.x` while the API is still being shaped. Once the core components have been used in a real project and props feel settled, ship `1.0.0`:
+Stay on `0.x.x` while the API is still being shaped. Once components have been used in a real project and props feel settled, ship `1.0.0`:
 
 ```bash
 npm version 1.0.0
@@ -183,8 +207,6 @@ npm publish
 git push && git push --tags
 ```
 
-From `1.0.0` onwards the rules above are strictly enforced.
-
 ---
 
 ## Contributing (for library maintainers)
@@ -193,7 +215,7 @@ From `1.0.0` onwards the rules above are strictly enforced.
 # Run the documentation site locally
 npm run dev
 
-# Build the library
+# Build the library only
 npm run build:lib
 
 # The docs site lives in src/app/