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

package/README.md

@@ -30,10 +30,33 @@ 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 "@exsto/ds/styles.css";
+@import "tailwindcss";
+@import "@exsto/ds/theme.css";
+```
+
+**The order matters, and `styles.css` has to come first.** It is a compiled
+Tailwind build, so its utilities land in the same cascade layer as yours, and at
+equal specificity the later rule wins. Import it after your Tailwind entry and
+its unconditional `.hidden` beats your `.md:table-cell`: responsive columns
+vanish, widths collapse. Library CSS before app CSS, as with any CSS dependency.
+
+`theme.css` is uncompiled on purpose. It carries the tokens, the `.dark` scope,
+the brand layer (Inter, `text-2xs`) 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 +96,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, brand layer, and the Tailwind `@theme` mapping |
 | `@exsto/ds/elements` | `<edx-*>` custom elements and `registerElements()` |
 
 ## Status