From 0f576cc56747245350d5ef2868fe16a83219dd9d Mon Sep 17 00:00:00 2001 From: Theo Sanderson Date: Mon, 1 Jun 2026 11:40:26 +0100 Subject: [PATCH 1/5] proposed styling guide --- architecture_docs/13_website_styling.md | 29 +++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 architecture_docs/13_website_styling.md diff --git a/architecture_docs/13_website_styling.md b/architecture_docs/13_website_styling.md new file mode 100644 index 0000000000..e554fc4ea6 --- /dev/null +++ b/architecture_docs/13_website_styling.md @@ -0,0 +1,29 @@ +# Styling Guide + +## The preferred approach: Tailwind + +We take a Tailwind-based approach to styling. The core idea is that styling lives next to the markup it applies to, rather than in separate stylesheets that drift out of sync with the components they describe. + +In practice this means three things, in order of preference. + +**Couple the CSS to the code with Tailwind classes.** Apply utility classes directly to elements. This keeps the styling and the structure in one place, so a component is fully described by reading its own source. Reach for this first; most UI needs nothing more. + +**Use Headless UI when the design is more complex.** When you need behaviour that goes beyond static markup — accessible dropdowns, modals, comboboxes, tabs, and similar interactive primitives — use [Headless UI](https://headlessui.com/) rather than reinventing the accessibility and state handling yourself. Headless UI gives you the unstyled, accessible behaviour, and you style it with Tailwind classes as usual. This pairing covers the large majority of complex cases. + +**Achieve uniformity by creating a shared component.** When the same styled element appears in several places and you want it to stay consistent, do not copy the class list around. Extract a shared component (for example a `Button` or `Card`) that owns the Tailwind classes in one place. Uniformity comes from reuse of components, not from a global stylesheet or a shared CSS class. If a pattern changes, you change it once. + +The rule of thumb: Tailwind classes by default, Headless UI for interactive complexity, and a shared component whenever you need the same thing to look the same in more than one place. + +## Other libraries we currently use + +We still depend on a few other styling and component libraries from earlier in the project's life. All of them are on a path away from, not toward. New work should avoid them where possible, and the notes below explain the specific reasons for each. + +**MUI — deprecated, do not use.** MUI is being deprecated and should not be used in new code. The main reason is that it plays badly with server-side rendering (SSR), which causes problems for us. Do not introduce new MUI components, and prefer migrating existing ones to the Tailwind approach when you touch them. + +**Daisy UI — avoid.** In Theo's view, Daisy UI causes confusion, and the recommendation is to deprecate and avoid it. Treat it the same as MUI for new work: don't add it, and lean toward removing it where practical. + +**Flowbite — minimise.** We use Flowbite for cases where we didn't have a ready alternative and the only other option was MUI — which we avoid because of its SSR issues. Flowbite is therefore a stopgap rather than a recommendation. Keep its use to a minimum, and prefer building with Tailwind, Headless UI, or a shared component when a viable alternative exists. + +## Summary + +Default to Tailwind utility classes coupled to your markup. Use Headless UI for complex, interactive, accessible components. Create a shared component whenever you need consistency across the codebase. Avoid MUI and Daisy UI in new code, and keep Flowbite to a minimum. From 1f4deec618b592717f9435104f07015e479952d1 Mon Sep 17 00:00:00 2001 From: Theo Sanderson Date: Mon, 1 Jun 2026 11:41:35 +0100 Subject: [PATCH 2/5] Update 13_website_styling.md --- architecture_docs/13_website_styling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/architecture_docs/13_website_styling.md b/architecture_docs/13_website_styling.md index e554fc4ea6..bc1dc24224 100644 --- a/architecture_docs/13_website_styling.md +++ b/architecture_docs/13_website_styling.md @@ -10,7 +10,7 @@ In practice this means three things, in order of preference. **Use Headless UI when the design is more complex.** When you need behaviour that goes beyond static markup — accessible dropdowns, modals, comboboxes, tabs, and similar interactive primitives — use [Headless UI](https://headlessui.com/) rather than reinventing the accessibility and state handling yourself. Headless UI gives you the unstyled, accessible behaviour, and you style it with Tailwind classes as usual. This pairing covers the large majority of complex cases. -**Achieve uniformity by creating a shared component.** When the same styled element appears in several places and you want it to stay consistent, do not copy the class list around. Extract a shared component (for example a `Button` or `Card`) that owns the Tailwind classes in one place. Uniformity comes from reuse of components, not from a global stylesheet or a shared CSS class. If a pattern changes, you change it once. +**Achieve uniformity by creating a shared component.** When the same styled element appears in several places and you want it to stay consistent, this can be achieved by extracting a shared component (for example a `Button` or `Card`) that owns the Tailwind classes in one place. Uniformity comes from reuse of components, not from a global stylesheet or a shared CSS class. The rule of thumb: Tailwind classes by default, Headless UI for interactive complexity, and a shared component whenever you need the same thing to look the same in more than one place. From 6b13f8e225154d07a3e898416ce74774f3e924cd Mon Sep 17 00:00:00 2001 From: Theo Sanderson Date: Mon, 1 Jun 2026 11:50:23 +0100 Subject: [PATCH 3/5] Update 13_website_styling.md --- architecture_docs/13_website_styling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/architecture_docs/13_website_styling.md b/architecture_docs/13_website_styling.md index bc1dc24224..01cddfc803 100644 --- a/architecture_docs/13_website_styling.md +++ b/architecture_docs/13_website_styling.md @@ -4,7 +4,7 @@ We take a Tailwind-based approach to styling. The core idea is that styling lives next to the markup it applies to, rather than in separate stylesheets that drift out of sync with the components they describe. -In practice this means three things, in order of preference. +In practice this means three things. **Couple the CSS to the code with Tailwind classes.** Apply utility classes directly to elements. This keeps the styling and the structure in one place, so a component is fully described by reading its own source. Reach for this first; most UI needs nothing more. From 202c6f2442764061937ed797df8de422ba83dbea Mon Sep 17 00:00:00 2001 From: Theo Sanderson Date: Wed, 3 Jun 2026 13:31:03 +0100 Subject: [PATCH 4/5] update --- architecture_docs/13_website_styling.md | 26 ++++++++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) diff --git a/architecture_docs/13_website_styling.md b/architecture_docs/13_website_styling.md index 01cddfc803..c4a41db487 100644 --- a/architecture_docs/13_website_styling.md +++ b/architecture_docs/13_website_styling.md @@ -6,6 +6,28 @@ We take a Tailwind-based approach to styling. The core idea is that styling live In practice this means three things. +**Use our pre-existing components that are already styled with Tailwind**. Here are some of the components that are available. + +``` + // variant: neutral|primary|ghost|outline + // size: md|sm|xs, also `circle` + + // size sm|md, `outline` for black tick + // `styled` for the bordered look + // decorative; pass `label` for role=status + +… // white dialog panel (use inside Headless UI Dialog) +… // level error|warning +{trigger} // variant info|warning|error + + // hover/focus-open, no JS state + … + + + +… // tabs are role='tab' +``` + **Couple the CSS to the code with Tailwind classes.** Apply utility classes directly to elements. This keeps the styling and the structure in one place, so a component is fully described by reading its own source. Reach for this first; most UI needs nothing more. **Use Headless UI when the design is more complex.** When you need behaviour that goes beyond static markup — accessible dropdowns, modals, comboboxes, tabs, and similar interactive primitives — use [Headless UI](https://headlessui.com/) rather than reinventing the accessibility and state handling yourself. Headless UI gives you the unstyled, accessible behaviour, and you style it with Tailwind classes as usual. This pairing covers the large majority of complex cases. @@ -18,9 +40,7 @@ The rule of thumb: Tailwind classes by default, Headless UI for interactive comp We still depend on a few other styling and component libraries from earlier in the project's life. All of them are on a path away from, not toward. New work should avoid them where possible, and the notes below explain the specific reasons for each. -**MUI — deprecated, do not use.** MUI is being deprecated and should not be used in new code. The main reason is that it plays badly with server-side rendering (SSR), which causes problems for us. Do not introduce new MUI components, and prefer migrating existing ones to the Tailwind approach when you touch them. - -**Daisy UI — avoid.** In Theo's view, Daisy UI causes confusion, and the recommendation is to deprecate and avoid it. Treat it the same as MUI for new work: don't add it, and lean toward removing it where practical. +**MUI — deprecated, do not use.** MUI is deprecated in our code, and used only in a handful of places. It should not be used in new code. The main reason is that it plays badly with server-side rendering (SSR), which causes problems for us. Do not introduce new MUI components, and prefer migrating existing ones to the Tailwind approach when you touch them. **Flowbite — minimise.** We use Flowbite for cases where we didn't have a ready alternative and the only other option was MUI — which we avoid because of its SSR issues. Flowbite is therefore a stopgap rather than a recommendation. Keep its use to a minimum, and prefer building with Tailwind, Headless UI, or a shared component when a viable alternative exists. From 63ceed410d1acd76bba03e86748eeaa6c5993384 Mon Sep 17 00:00:00 2001 From: Theo Sanderson Date: Wed, 3 Jun 2026 13:32:13 +0100 Subject: [PATCH 5/5] update --- architecture_docs/13_website_styling.md => website/STYLING.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename architecture_docs/13_website_styling.md => website/STYLING.md (100%) diff --git a/architecture_docs/13_website_styling.md b/website/STYLING.md similarity index 100% rename from architecture_docs/13_website_styling.md rename to website/STYLING.md