The best way to control Claude Code, Codex and more from any computer or phone
| 1 | # Web UI |
| 2 | |
| 3 | ## Primitives |
| 4 | |
| 5 | Controls come from [`components/ui`](../../apps/web/src/components/ui). |
| 6 | [AGENTS.md](../../AGENTS.md#taste) says how to use and extend them. |
| 7 | |
| 8 | Don't style a raw `<button>`, `<input>`, `<select>`, or `<textarea>` to look like a control a |
| 9 | primitive provides. Raw elements are right when the element isn't that control: semantic rows, tabs, |
| 10 | resize handles, swatches, editor surfaces, anything whose behavior or geometry differs by design. |
| 11 | |
| 12 | ## Styles |
| 13 | |
| 14 | Style with Tailwind classes in the component that renders the element. |
| 15 | |
| 16 | - Global CSS, in [`index.css`](../../apps/web/src/index.css) or any other stylesheet, is only for |
| 17 | what classes on the owning component can't express: generated Markdown or imperative DOM, custom |
| 18 | elements and shadow roots, animations, runtime theme variables, and browser or Electron |
| 19 | integration. |
| 20 | - No `style={{ ... }}` or inline `<style>` for static values a class covers. Values computed at |
| 21 | runtime are fine. |
| 22 | - Theme-only rules use `@variant dark` and `@variant light`, not `.dark` selectors. |
| 23 | |
| 24 | ## Composition |
| 25 | |
| 26 | The composer banners are the reference. |
| 27 | |
| 28 | - [`ComposerBanner.tsx`](../../apps/web/src/components/chat/ComposerBanner.tsx) exports one object |
| 29 | of small slots. Slots own their classes, take `className`, and spread the rest of their props, |
| 30 | merging classes with `cn`. Variants and density are props on `Root`. A slot that needs a control |
| 31 | renders `Button`. |
| 32 | - [`ComposerBannerStack.tsx`](../../apps/web/src/components/chat/ComposerBannerStack.tsx) composes |
| 33 | the slots and owns only stack behavior: priority, expand and collapse, dismiss transitions. |
| 34 | |
| 35 | Build new UI the same way. Compose or extend a component instead of copying its markup and classes. |
| 36 | When a call site repeats a treatment another one already uses, make it a variant or a slot on the |
| 37 | shared component. A new composer banner or notice uses the `ComposerBanner` slots. |
| 38 | |
| 39 | ## Handlers in large components |
| 40 | |
| 41 | V8 gives every closure created in one render a single shared scope. A memoized handler keeps |
| 42 | the scope of the render that created it, and that scope holds the other memoized values of that |
| 43 | render. When handlers in one component change at different times, each keeps an older scope that |
| 44 | holds older handlers, and old renders, with their server config and thread data, stay in memory |
| 45 | for as long as the component is mounted. React Compiler's memoized closures do the same. |
| 46 | |
| 47 | In large, long-lived components such as `ChatView` and `ChatComposer`, write handlers as plain |
| 48 | functions and wrap them with [`useStableCallback`](../../apps/web/src/hooks/useStableCallback.ts) |
| 49 | only where they leave the component: props, hook dependency arrays, and effect or memo bodies. |
| 50 | Calls inside the component keep the plain function, so work that resumes after an `await` still |
| 51 | acts on the render it started in. A function that a child calls during render, or after an |
| 52 | `await`, comes from a module-level factory memoized on its inputs, so its closure keeps only |
| 53 | those inputs. |
| 54 | |
| 55 | ## React Compiler |
| 56 | |
| 57 | The compiler memoizes a component or hook only when it can prove the code follows React's rules. |
| 58 | Anything it can't prove, such as reading a ref during render or calling `setState` from an effect, |
| 59 | makes it skip the whole function without a build error. Lint reports each skip as a |
| 60 | `react(...)` warning with the note "React Compiler skipped optimizing this component or hook". |
| 61 | |
| 62 | Every file under `apps/web/src` must compile. Lint makes those rules errors there, and |
| 63 | `t3code/no-manual-memo` rejects `useMemo` and `useCallback`, which the compiler makes redundant; |
| 64 | no upstream rule bans them outright. It also rejects `"use memo"`. The compiler withholds a cache |
| 65 | scope when a value reaches plain function calls on both sides of a hook call. A `"use memo"` |
| 66 | helper forces one, but hides the ordering problem. Fix the order instead: plain uses of a value go |
| 67 | before the hook, or the helper is inlined. A `use*` helper that calls no hook is compiled as a |
| 68 | plain function and caches nothing, so a derived-value helper reads its source hook itself instead |
| 69 | of taking the value as an argument. `t3code/no-hookless-use-function` rejects a `use*` function |
| 70 | that calls no hook. Lint misses some bailouts, notably `try` with `finally` and |
| 71 | `throw` inside `try`, so [`reactCompilerCoverage.test.ts`](../../apps/web/src/reactCompilerCoverage.test.ts) |
| 72 | compiles every file and fails on any skip. Async handlers rarely need `try`: an |
| 73 | atom command settles into a result, so cleanup can follow the `await`. `useStableCallback` still |
| 74 | marks handlers that leave a large component, as described above. |