docs: update frontend contributing guide for shadcn/ui and TailwindCSS migration #18702

BrunoQuaresma · 2025-07-01T19:19:08Z

Update the frontend contributing guide to reflect the current architecture and ongoing migration from MUI to shadcn/ui and from Emotion to TailwindCSS.

Key changes:

Updated tech stack to include TailwindCSS, shadcn/ui, Lucide React, and Biome
Added migration status section with current progress (~210 MUI files, ~41 migrated)
Added development commands section with pnpm commands and pre-PR checklist
Rewrote UI components section to prioritize shadcn/ui over MUI
Completely updated styling section to focus on TailwindCSS
Enhanced accessibility section with TailwindCSS examples
Added comprehensive migration guide with practical examples and checklists
Documented semantic color system and best practices

…S migration Update the frontend contributing guide to reflect the current architecture and ongoing migration from MUI to shadcn/ui and from Emotion to TailwindCSS. Key changes: - Updated tech stack to include TailwindCSS, shadcn/ui, Lucide React, and Biome - Added migration status section with current progress (~210 MUI files, ~41 migrated) - Added development commands section with pnpm commands and pre-PR checklist - Rewrote UI components section to prioritize shadcn/ui over MUI - Completely updated styling section to focus on TailwindCSS - Enhanced accessibility section with TailwindCSS examples - Added comprehensive migration guide with practical examples and checklists - Documented semantic color system and best practices Co-authored-by: BrunoQuaresma <3165839+BrunoQuaresma@users.noreply.github.com>

Ran make fmt and frontend linting to ensure code quality: - Go formatting: passed - Terraform formatting: passed - Frontend formatting (Biome): passed (1124 files, no fixes needed) - Frontend linting (Biome): passed (1124 files, no issues) No changes were required as the code already meets all formatting standards. Co-authored-by: BrunoQuaresma <3165839+BrunoQuaresma@users.noreply.github.com>

Fixed 11 markdown linting errors found by markdownlint-cli2: - MD022: Added blank lines around headings - MD032: Added blank lines around lists (9 instances) - MD031: Added blank lines around fenced code blocks - MD040: Added language specification to fenced code block All markdown linting rules now pass with 0 errors. Co-authored-by: BrunoQuaresma <3165839+BrunoQuaresma@users.noreply.github.com>

github-actions · 2025-07-01T19:32:46Z

docs/about/contributing/frontend.md

🚫 [linkspector] _{reported by reviewdog 🐶}
Cannot reach https://stackoverflow.com/questions/69711888/react-testing-library-getbyrole-is-performing-extremely-slowly Status: 403

coder/docs/about/contributing/frontend.md

Line 502 in 2de7330

- <https://stackoverflow.com/questions/69711888/react-testing-library-getbyrole-is-performing-extremely-slowly>

Parkreiner · 2025-07-02T13:51:29Z

@BrunoQuaresma Forgot to message you about this earlier, but I added myself as a reviewer for this PR. I figured that I might be a good guinea pig, since I've been away from coder/coder for so long, and am just now getting back to contributing more consistently

BrunoQuaresma · 2025-07-02T14:40:12Z

@Parkreiner sure thing! Welcome back my friend.

Parkreiner

Not approving just yet, because I don't know what we want our goals for the README to be. Just pointed out things that looked funny so far

Parkreiner · 2025-07-02T15:50:22Z

docs/about/contributing/frontend.md

+```bash
+# Development
+pnpm dev                    # Start Vite development server
+pnpm storybook --no-open    # Run Storybook for component development


I think we should remove the --no-open part. I'd imagine that most people running Storybook locally would want it to open in the browser

Parkreiner · 2025-07-02T15:52:32Z

docs/about/contributing/frontend.md

+pnpm lint                   # Run complete linting suite (Biome + TypeScript + circular deps + knip)
+pnpm lint:fix               # Auto-fix linting issues where possible
+pnpm format                 # Format code with Biome (always run before PR)
+pnpm check                  # Type-check with TypeScript


I think this is wrong, and we need to swap it out for pnpm lint:types

Parkreiner · 2025-07-02T15:53:39Z

docs/about/contributing/frontend.md

+2. `pnpm lint` - Fix linting issues
+3. `pnpm format` - Format code consistently
+4. `pnpm test` - Run affected unit tests
+5. Visual check in Storybook if component changes


Suggested change

5. Visual check in Storybook if component changes

5. Check Storybook for any components affected by code changes

Parkreiner · 2025-07-02T15:56:15Z

docs/about/contributing/frontend.md

+### Current State
+
+- **~210 files** still use MUI components (`@mui/material`)
+- **~41 components** have been migrated to use TailwindCSS classes
+- **shadcn/ui components** are being added incrementally to `src/components/`
+- **Emotion CSS** is deprecated but still present in legacy components


I think we should delete this section entirely, because it will quickly get out of date

Parkreiner · 2025-07-02T15:59:53Z

docs/about/contributing/frontend.md

+
+When working on existing components:
+
+1. **Prefer shadcn/ui components** over MUI when available


Suggested change

1. **Prefer shadcn/ui components** over MUI when available

These instructions assume that you have already checked the `src/components` directory, and it doesn't have the right component you need.

1. **Prefer components in this order:** `shadcn/ui`, Radix, MUI

Parkreiner · 2025-07-02T19:48:29Z

docs/about/contributing/frontend.md

+// ❌ Before: MUI Button
+import { Button } from "@mui/material";
+
+<Button 
+  variant="contained" 
+  color="primary"
+  sx={{ margin: 2 }}
+  onClick={handleClick}
+>
+  Click me
+</Button>


This shows an example of not using tree-shaking, right? Wouldn't this need to be:

import Button from "@mui/material/Button";

?

Parkreiner · 2025-07-02T19:50:42Z

docs/about/contributing/frontend.md

+import { Button } from "components/Button";
+
+<Button 
+  variant="primary"


Our buttons don't have a primary variant, right?

Parkreiner · 2025-07-02T19:52:03Z

docs/about/contributing/frontend.md

+  <Label htmlFor="email">Email</Label>
+  <Input 
+    id="email"
+    className={errors.email ? "border-border-destructive" : ""}


We don't have the border-border-destructive class, right? It's just border-destructive?

Parkreiner · 2025-07-02T19:53:10Z

docs/about/contributing/frontend.md

+
+1. **Check existing implementations** in `src/components/` for patterns
+2. **Refer to shadcn/ui documentation** at [ui.shadcn.com](https://ui.shadcn.com/)
+3. **Ask in Discord** - the team is happy to help with migration questions


Do we want to add a link to the Discord here?

Parkreiner · 2025-07-02T19:53:58Z

docs/about/contributing/frontend.md

+When a shadcn/ui equivalent doesn't exist:
+
+1. **Check the shadcn/ui registry** for the component
+2. **Copy the component code** (don't use the CLI)
+3. **Adapt to our theme** using semantic color tokens
+4. **Add to `src/components/`** with proper folder structure
+5. **Create Storybook stories** for documentation
+6. **Add TypeScript types** for props
+7. **Include accessibility features** (ARIA attributes, keyboard support)


I don't now if this section should even be here

BrunoQuaresma requested review from f0ssel and a team July 1, 2025 19:19

BrunoQuaresma self-assigned this Jul 1, 2025

BrunoQuaresma requested review from brettkolodny and removed request for a team July 1, 2025 19:19

blink-so bot and others added 2 commits July 1, 2025 19:24

github-actions bot reviewed Jul 1, 2025

View reviewed changes

Parkreiner self-requested a review July 2, 2025 12:26

Parkreiner reviewed Jul 2, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: update frontend contributing guide for shadcn/ui and TailwindCSS migration #18702

docs: update frontend contributing guide for shadcn/ui and TailwindCSS migration #18702

BrunoQuaresma commented Jul 1, 2025

Uh oh!

github-actions bot Jul 1, 2025

Uh oh!

Parkreiner commented Jul 2, 2025

Uh oh!

BrunoQuaresma commented Jul 2, 2025

Uh oh!

Parkreiner left a comment

Uh oh!

Parkreiner Jul 2, 2025

Uh oh!

Parkreiner Jul 2, 2025

Uh oh!

Parkreiner Jul 2, 2025

Uh oh!

Parkreiner Jul 2, 2025

Uh oh!

Parkreiner Jul 2, 2025

Uh oh!

Parkreiner Jul 2, 2025

Uh oh!

Parkreiner Jul 2, 2025

Uh oh!

Parkreiner Jul 2, 2025

Uh oh!

Parkreiner Jul 2, 2025

Uh oh!

Parkreiner Jul 2, 2025

Uh oh!

Uh oh!

	5. Visual check in Storybook if component changes
	5. Check Storybook for any components affected by code changes


		When working on existing components:

		1. Prefer shadcn/ui components over MUI when available

	1. Prefer shadcn/ui components over MUI when available
	These instructions assume that you have already checked the `src/components` directory, and it doesn't have the right component you need.
	1. Prefer components in this order: `shadcn/ui`, Radix, MUI

docs: update frontend contributing guide for shadcn/ui and TailwindCSS migration #18702

Are you sure you want to change the base?

docs: update frontend contributing guide for shadcn/ui and TailwindCSS migration #18702

Conversation

BrunoQuaresma commented Jul 1, 2025

Uh oh!

github-actions bot Jul 1, 2025

Choose a reason for hiding this comment

Uh oh!

Parkreiner commented Jul 2, 2025

Uh oh!

BrunoQuaresma commented Jul 2, 2025

Uh oh!

Parkreiner left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!