create-gentiq-app 0.15.0-beta.1 → 0.15.0

package/README.md

@@ -109,6 +109,122 @@ left to run by hand.
 
 ---
 
+## Using Tailwind in a Gentiq app
+
+The scaffold ships **no Tailwind** — `gentiq/style.css` is already compiled, and the chat
+and admin UIs are fully styled by it. You only need Tailwind if you are writing your own
+components (a custom tool card, say). If you add it, read this section first: two Tailwind
+builds in one document need one extra line to coexist, and without it they break each
+other silently.
+
+### Why it needs care
+
+Tailwind guarantees that a variant (`md:`, `hover:`) is emitted *after* the plain utility
+it is meant to override — that is the whole reason `flex-col md:flex-row` works. The
+guarantee holds **per build**. Gentiq ships precompiled CSS, so adding Tailwind to your app
+creates a second, independently sorted set of utilities, and concatenating them destroys
+the ordering: whichever set lands later wins every tie, regardless of which stylesheet
+"owns" the class.
+
+Both directions are broken, and neither announces itself:
+
+| Your utilities last | Gentiq's utilities last |
+| --- | --- |
+| Your `.flex-col` beats gentiq's `.md:flex-row` — the admin header collapses into a vertical stack at every width | Gentiq's `.grid-cols-2` beats your `.sm:grid-cols-3` — your own grids stop responding |
+
+Reordering does not fix it, because the problem is not the order. It is that there are two
+sorts. The fix is to collapse them back to one.
+
+### The setup
+
+Put this at the top of `src/index.css`, and delete `import 'gentiq/style.css'` from
+`src/App.tsx` (this file has to load first, so it must own that import):
+
+```css
+/* Layer order for the document: gentiq's layers first, yours last. */
+@layer properties, gentiq-theme, gentiq-base, gentiq-components, gentiq-utilities,
+       theme, base, components, utilities;
+
+@import 'gentiq/style.css';
+
+/* Theme + utilities only — NOT `@import 'tailwindcss'`. That bundles preflight,
+   and gentiq's stylesheet already ships one; a second copy lands after gentiq's
+   rules and its `border: 0 solid` resets border-color to currentColor, which
+   paints every unstyled border in the app the foreground colour. */
+@import 'tailwindcss/theme.css' layer(theme);
+@import 'tailwindcss/utilities.css' layer(utilities);
+
+/* The line that actually makes the two coexist: scan gentiq's bundles so YOUR
+   build emits gentiq's classes too. One build, one sort, every variant back
+   after its base utility. Gentiq's precompiled layer is then shadowed for every
+   class you regenerate, and still supplies its custom `@utility` rules (`glass`,
+   the loader animations), whose names contend with nothing you emit. */
+@source '../node_modules/gentiq/dist/gentiq-index.es.js';
+@source '../node_modules/gentiq/dist/gentiq-admin.es.js';
+
+/* Gentiq's design tokens, registered with YOUR Tailwind instance. Gentiq declares
+   the same map in its own `@theme inline`, but that lives in its compiled
+   stylesheet, which your compiler never sees — so without this block utilities
+   like `hover:border-primary/40` silently generate nothing. `inline` is what makes
+   them resolve at runtime, so ThemeProvider can keep rewriting accent and theme. */
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+}
+```
+
+Do not set `body { font-family: … !important }` here. `ThemeProvider` composes the
+configured face with `var(--font-script)` and writes it inline to `<html>` and `<body>`;
+an `!important` rule beats that inline style and strips the per-script fallback, leaving
+Persian and Arabic text in a serif default.
+
+The `@source` lines cost roughly 10–13 kB gzipped, because your build re-emits the
+utilities gentiq already shipped. That is the price of a correct cascade; the duplicate
+rules are identical and fully shadowed.
+
+### Layers
+
+Gentiq publishes into `gentiq-theme`, `gentiq-base`, `gentiq-components` and
+`gentiq-utilities` rather than the bare `theme` / `base` / `components` / `utilities`
+(versions up to and including `0.15.0-beta.1` used the bare names). Those generic names belong to your document, and gentiq
+claiming them is what let the two builds merge by accident in the first place. Gentiq
+deliberately does **not** pre-register your layer names, so your stylesheet keeps the
+position it has always had; the `@layer` statement above is where you decide the order.
+
+The setup above works against older versions too — the `gentiq-*` layers just stay empty
+and gentiq's stylesheet lands in `theme` / `base` / `utilities` instead, still ahead of
+your regenerated superset.
+
+### Checking it
+
+The admin dashboard header is the fastest canary — it is the layout in the product that
+leans hardest on `md:` overrides. Open `/admin` above 768px: the logo and the navigation
+tabs sit on one row. If they are stacked vertically, your utilities are beating gentiq's
+variants and `@source` is missing or pointing at the wrong path.
+
+---
+
 ## Why Gentiq?
 
 Unlike generic boilerplates, Gentiq is built with **developer velocity** and **production scalability** in mind. It provides the "boring" parts of AI development—authentication, rate limiting, and persistence—so you can focus on building your agents.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-gentiq-app",
-  "version": "0.15.0-beta.1",
+  "version": "0.15.0",
   "description": "CLI to scaffold a new Gentiq application",
   "type": "module",
   "bin": {