Orders

Order ACME-1042 from Grace

{number}

{customer}

{total}

} ``` ```tsx // renders class="rounded-lg border bg-background p-8 shadow-md" ``` Don't join with a template string (`` `p-4 ${className}` ``). Both padding classes reach the browser and the result depends on stylesheet order. ## Build variants with cva A component with variants (a status, a size) maps each one to classes. [class-variance-authority](https://cva.style/docs) is installed by `kitr add tailwind`, and the components from `kitr ui add` use it: ```tsx // app/components/orders/order-status-badge.tsx import { cva, type VariantProps } from 'class-variance-authority' import { cn } from '@kitr/tailwind' import type { ReactNode } from 'react' export const orderStatusBadge = cva('inline-flex items-center rounded-md px-2 py-0.5 text-xs font-medium', { variants: { status: { paid: 'bg-primary text-primary-foreground', pending: 'bg-muted text-muted-foreground', refunded: 'bg-destructive text-destructive-foreground', }, size: { sm: 'text-xs', md: 'px-3 py-1 text-sm', }, }, defaultVariants: { status: 'pending', size: 'sm' }, }) type Props = VariantProps & { className?: string; children: ReactNode } export function OrderStatusBadge({ status, size, className, children }: Props) { return {children} } ``` ```tsx Refunded // class="inline-flex items-center rounded-md font-medium bg-destructive text-destructive-foreground px-3 py-1 text-sm" ``` `cn()` around the `cva` call is what lets `size: 'md'` replace the base `px-2 py-0.5 text-xs` instead of adding to it. `cva` is also re-exported from `@kitr/theme`, if you would rather import it from there. ## Teach cn() about your own tokens tailwind-merge only knows Tailwind's built-in scales. A custom font size such as `text-display` looks like a colour to it, so `cn('text-display', 'text-primary')` drops `text-display`. Build your own `cn` with `extendTailwindMerge` and list the new values: ```ts // app/lib/cn.ts import { clsx, type ClassValue } from 'clsx' import { extendTailwindMerge } from 'tailwind-merge' const merge = extendTailwindMerge({ extend: { theme: { text: ['display'] } }, }) export function cn(...inputs: ClassValue[]) { return merge(clsx(inputs)) } cn('text-display', 'text-primary') // => 'text-display text-primary' ``` Custom colours need nothing: `cn('bg-success', 'bg-primary')` already returns `'bg-primary'`. `clsx` and `twMerge` are also exported from `@kitr/tailwind`, for the cases where you want only one half of `cn()`. ## Tell Tailwind where your classes are Tailwind generates only the classes it finds in your source files. `@source '../'` in `app/styles/app.css` points it at `app/`. Classes written anywhere else need their own line: ```css /* app/styles/app.css */ @import 'tailwindcss'; @import '@kitr/tailwind/preset.css'; @import '@kitr/theme/styles.css'; @source '../'; @source '../../server/mail'; @source '../../node_modules/@acme/ui/dist'; ``` Tailwind finds classes by reading the files as text, so a class has to appear whole: ```tsx // Don't: Tailwind never sees "bg-primary" or "bg-destructive" // Do: both full class names are in the source ``` A class that is missing from the build shows up in the HTML but has no style. That is almost always a class built from pieces or a folder no `@source` covers. ## Style kitr's own components Headless kitr components mark their parts with `data-kitr` attributes, so you can reach them with Tailwind's arbitrary variants. The field wrapper from [forms](/packages/forms) is one: ```tsx // app/components/orders/refund-reason-field.tsx import { FieldInput, FormField } from '@kitr/forms' export function RefundReasonField() { return ( ) } ``` For a finished look, `kitr ui add form` copies a styled version into `app/components/ui/form.tsx`. Every component `kitr ui add` copies is plain Tailwind on the theme classes and `cn()`, and the code is yours to change. ## Use plain Tailwind colors To use Tailwind without kitr's tokens, remove the preset import, and the theme stylesheet if nothing else needs it: ```css /* app/styles/app.css */ @import 'tailwindcss'; @source '../'; ``` Then set `preset: false` in `config/tailwind.ts` so the file still describes the project. Without the preset, `bg-primary` and the other theme classes stop existing, `dark:` goes back to following `prefers-color-scheme`, and components from `kitr ui add` lose their colours. ## Wire Tailwind into a custom Vite config The `kitr()` plugin loads `@tailwindcss/vite` for you. If you build a Vite config without `kitr()`, or want to control the plugin order, turn it off there and add `kitrTailwind()` from `@kitr/tailwind/vite`. It returns exactly `@tailwindcss/vite`'s plugins: ```ts // vite.config.ts import { defineConfig } from 'vite' import { kitr } from '@kitr/vite' import { kitrTailwind } from '@kitr/tailwind/vite' export default defineConfig({ plugins: [kitrTailwind(), kitr({ plugins: { tailwind: false } })], }) ``` Don't add Tailwind's plugin while `kitr()` also loads it. The CSS is then processed twice. ## Fix styles that do not apply Most Tailwind problems in a kitr app come from one of a few causes. Check them in this order: | Symptom | Cause | Fix | | --- | --- | --- | | No Tailwind styles at all | `app/styles/app.css` is not imported, or `@kitr/tailwind` is missing from `packages` in `kitrrc.ts` so the Vite plugin is not loaded. | Import `#app/styles/app.css` in `app/document.tsx`; run `kitr doctor`. | | `bg-primary` and other theme classes do nothing | The preset import is missing from `app/styles/app.css`. | Add `@import '@kitr/tailwind/preset.css';` after `@import 'tailwindcss';`. | | Theme classes resolve but have no colour | `@kitr/theme/styles.css` is not imported, so the `--kitr-*` variables are undefined. | Add `@import '@kitr/theme/styles.css';`. | | `dark:` classes never apply | Nothing sets `data-theme="dark"` on ``. | Mount the [theme](/packages/theme) provider and switch with `useTheme()`. | | One class works in one file but not another | The file is outside every `@source` folder, or the class is built from pieces. | Add an `@source` line, or write the whole class name. | | A caller's `className` does not win | The component joins classes with a template string. | Use `cn(base, className)`. | | A custom class disappears when merged | tailwind-merge treats it as a conflicting class. | Extend it ([Teach cn() about your own tokens](#teach-cn-about-your-own-tokens)). | `kitr doctor` checks the part kitr owns: it warns when `vite.config.ts` does not use the `kitr()` plugin. In the browser's devtools, a class that appears on the element but has no matching rule in the Styles panel was not generated; one that has a rule crossed out was overridden. ## Testing Tests do not build CSS. The `vitest.config.ts` that kitr writes runs `kitr({ plugins: { tailwind: false } })`, so a test checks which classes a component renders, not what they look like. Test `cn()` merges and variant classes directly: ```tsx // app/components/orders/order-status-badge.test.tsx import { render, screen } from '@testing-library/react' import { cn } from '@kitr/tailwind' import { describe, expect, it } from 'vitest' import { OrderStatusBadge, orderStatusBadge } from './order-status-badge' describe('OrderStatusBadge', () => { it('uses the theme colours for each status', () => { expect(orderStatusBadge({ status: 'paid' })).toContain('bg-primary text-primary-foreground') expect(orderStatusBadge()).toContain('bg-muted text-muted-foreground') }) it('lets a size replace the base padding', () => { render( Refunded , ) const badge = screen.getByText('Refunded') expect(badge.className).toContain('px-3 py-1 text-sm') expect(badge.className).not.toContain('px-2') }) it('lets callers override classes', () => { render( Paid , ) expect(screen.getByText('Paid').className.split(' ')).toContain('rounded-lg') expect(screen.getByText('Paid').className.split(' ')).not.toContain('rounded-md') }) it('merges with cn the way the component does', () => { expect(cn('px-2 py-1', 'px-4')).toBe('py-1 px-4') expect(cn('text-sm', { 'text-lg': true }, false, undefined)).toBe('text-lg') }) }) ``` To check how a page actually looks, light and dark, use a browser test with [Playwright](https://playwright.dev/docs/screenshots) against `npm run dev`. ## Next steps - [API reference](/packages/tailwind/api): `cn`, `defineConfig`, `TailwindConfig` and `kitrTailwind`. - [Tailwind CSS docs](https://tailwindcss.com/docs): every utility, variant and the `@theme` syntax. - [Theme](/packages/theme): the tokens behind the classes, `useTheme()` and `kitr ui add`. - [Forms](/packages/forms): headless fields you style with the `data-kitr` attributes. - [Project structure](/docs/project-structure): where `app/styles/app.css` and `config/` sit.