@exsto/ds 0.0.1-rc.1 → 0.0.1-rc.2

package/README.md

@@ -30,10 +30,26 @@ That is the whole setup. **You do not need Tailwind.** `styles.css` ships
 precompiled: it carries the design tokens plus every utility the components
 themselves use.
 
-If you *do* use Tailwind, note that `styles.css` does not generate utilities for
-your own markup. Your Tailwind build does that, as it already would; this file
-only guarantees the components look right. The tokens are plain CSS custom
-properties on `:root`, so your own styles can read them.
+### If you use Tailwind
+
+`styles.css` is compiled output, so it only contains the utilities the components
+themselves use. To write `bg-card` or `text-muted-foreground` in your *own*
+markup, import the token layer as well and let your Tailwind build generate the
+whole vocabulary:
+
+```css
+@import "tailwindcss";
+@import "@exsto/ds/theme.css";
+@import "@exsto/ds/styles.css";
+```
+
+`theme.css` is uncompiled on purpose: it carries the tokens, the `.dark` scope
+and the `@theme` mapping Tailwind needs to turn them into utilities. Do not copy
+that block into your app, or it will drift from the design system.
+
+Without it some token utilities still work, because our components happen to use
+them, but the coverage is incidental: roughly half of `bg-*` and nearly every
+`border-*` is absent.
 
 ### Dark mode
 
@@ -73,6 +89,7 @@ supply your own sheet. Calling it more than once is harmless.
 |---|---|
 | `@exsto/ds` | React components (the default) |
 | `@exsto/ds/styles.css` | Precompiled tokens and component styles |
+| `@exsto/ds/theme.css` | Uncompiled tokens plus the Tailwind `@theme` mapping |
 | `@exsto/ds/elements` | `<edx-*>` custom elements and `registerElements()` |
 
 ## Status