Skip to content

Update docs #16315

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
wackerow merged 2 commits into from
Sep 21, 2025
Merged

Update docs #16315

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
96c51e7
update docs
pettinarip Sep 19, 2025
c0339fe
chore: lowercase shadcn naming
wackerow Sep 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ This is the official Ethereum.org website - a Next.js application that serves as
- **next-mdx-remote 5.0+** - MDX content processing
- **Framer Motion 10.13+** - Animations and transitions
- **Radix UI** - Accessible component primitives
- **ShadCN/UI** - Component library built on Radix UI
- **shadcn/ui** - Component library built on Radix UI
- **Recharts** - Data visualization
- **Viem/Wagmi** - Ethereum blockchain integration

Expand Down
2 changes: 1 addition & 1 deletion docs/applying-storybook.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ It's as easy as running `pnpm storybook` to boot up a dedicated localhost to see

## Setting up a component's stories

> 🚨 NOTE: This project uses Storybook v7, using the Component Story Format v3 and the `satisfies` keyword to define the type of the meta object. The following documentation outlines preferences in setup as it relates to this version. You can refer to the [main docs](https://storybook.js.org/docs/get-started) if you need any additional details
> 🚨 NOTE: This project uses Storybook v8.6+, using the Component Story Format v3 and the `satisfies` keyword to define the type of the meta object. The following documentation outlines preferences in setup as it relates to this version. You can refer to the [main docs](https://storybook.js.org/docs/get-started) if you need any additional details

A Storybook "story" is an instance of a component in a certain state or with certain parameters applied to show an alternative version of the component.

Expand Down
63 changes: 28 additions & 35 deletions docs/best-practices.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,59 +102,52 @@ export default ComponentName

## Styling

We use [Chakra UI](https://chakra-ui.com/).
We use [Tailwind CSS](https://tailwindcss.com/) as our primary styling approach, combined with the [shadcn/ui](https://ui.shadcn.com/) component library built on [Radix UI](https://www.radix-ui.com/) primitives.

`src/@chakra-ui/theme.ts` - Holds all the theme configuration. This is where you can find the colors, fonts, component themes, variants, etc.
### Styling Approach

- Wrappers or layout divs
- **Primary**: Tailwind CSS utility classes
- **Component variants**: Use `class-variance-authority` (cva) for component variants
- **Dynamic classes**: Use `cn()` utility function (combines clsx + tailwind-merge)
- **Responsive design**: Mobile-first approach with Tailwind breakpoints (`sm:`, `md:`, `lg:`, `xl:`, `2xl:`)

Use the [native layouts components](https://chakra-ui.com/docs/components/box)
### Layout Components

```tsx
<Stack direction='row'>
```

Center things using the `<Center />` component
Use standard HTML elements with Tailwind classes for layouts:

```tsx
<Center h="100px">
```
// Flexbox layouts
<div className="flex items-center justify-between">
<div className="flex flex-col gap-4">

- Group buttons using `<ButtonGroup />` or `<Wrap />`
// Grid layouts
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">

```tsx
<ButtonGroup variant='outline' spacing={2}>
<Button>Button 1</Button>
<Button>Button 2</Button>
</ButtonGroup>

// or
<Wrap spacing={2}>
<WrapItem><Button variant="outline">Button 1</Button></WrapItem>
<WrapItem><Button variant="outline">Button 2</Button></WrapItem>
</Wrap>
// Centering
<div className="flex items-center justify-center min-h-screen">
```

- Breakpoints
### Component Styling

Use [the Chakra default breakpoints](https://www.chakra-ui.com/docs/theming/customization/breakpoints).
Use shadcn/ui components for interactive elements:

```tsx
<Container display={{ base: "block", sm: "flex" }} />
import { Button } from "@/components/ui/button"

<Button variant="outline" size="sm">
Click me
</Button>
```

- Theme colors
### Colors and Theming

Use CSS custom properties defined in the design system:

```tsx
<Text color="primary.base" bg="background.base" />
<div className="bg-primary text-primary-foreground">
<div className="border border-border bg-background">
```

> Note the dotted notation. In Chakra, the values are referred to as "semantic tokens" and the new theme applies a nested structure of like tokens for better organization. See [semanticTokens.ts](../src/@chakra-ui/semanticTokens.ts)

> Note 2: all the previous colors defined in the old theme `src/theme.ts` were
> ported into the new theme for compatibility reasons. Those colors will
> transition out of the codebase as we adopt the DS colors.

- [Framer Motion](https://www.framer.com/motion/) - An open source and production-ready motion library for React on the web, used for our animated designs
- **Emojis**: We use [Twemoji](https://twemoji.twitter.com/), an open-source emoji set created by Twitter. These are hosted by us, and used to provide a consistent experience across operating systems.

Expand Down Expand Up @@ -236,7 +229,7 @@ Wrap icon in a div for circular backgrounds, and color using background:

## Using custom `Image` component

[Next Image](https://nextjs.org/docs/pages/api-reference/components/image) is the component of choice to handle responsive images. However, we use a custom version of this component that is properly optimized with Chakra. This way we can use style props from Chakra but still be able to forward common or Next Image-specific props to the component for correct usage and rendering.
[Next.js Image](https://nextjs.org/docs/app/api-reference/components/image) is the component of choice to handle responsive images. We use a custom version of this component that integrates with our design system.

```tsx
import { Image } from "@/components/Image"
Expand Down
16 changes: 9 additions & 7 deletions docs/code-conventions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,16 +39,18 @@ const Component = ({ title, label, ...props }: ComponentProps) => {
}

/**
* Components using `forwardRef` from the Chakra UI package
* Components using `forwardRef` from React
*
* The first argument of the generic types is the props type signature.
*
* For the second argument of the generic types, you are declaring the primary element type that the component will render.
* This could be a `div`, `span`, `button`, etc. or a custom component (typeof Button) if said component is being used in the return.
* Use React.forwardRef when you need to forward refs to DOM elements or child components.
* The ref type should match the element being rendered (HTMLDivElement, HTMLButtonElement, etc.)
*/
const Component = forwardRef<ComponentProps, "div">(
const Component = React.forwardRef<HTMLDivElement, ComponentProps>(
({ title, label, ...props }, ref) => {
// Component code
return (
<div ref={ref} {...props}>
{/* Component code */}
</div>
)
}
)
```
Expand Down
16 changes: 9 additions & 7 deletions docs/stack.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,16 @@

- [Node.js](https://nodejs.org/)
- [pnpm](https://pnpm.io/) - Fast, disk space efficient package manager
- [NextJS](https://nextjs.org/)
- React framework that provides some goodies out of the box (pages router, SSG, SSR, i18n support, Image component, etc)
- [Next.js 14](https://nextjs.org/)
- React framework with App Router, SSG, SSR, i18n support, Image component, etc.
- Configurable in `next.config.js`
- [NextJS Tutorial](https://nextjs.org/learn)
- [NextJS Docs](https://nextjs.org/docs)
- [React](https://react.dev/) - A JavaScript library for building component-based user interfaces
- [Typescript](https://www.typescriptlang.org/) - TypeScript is a strongly typed programming language that builds on JavaScript
- [Chakra UI](https://chakra-ui.com/) - A UI library (Migration in progress)
- [Tailwind CSS](https://tailwindcss.com/) - Utility-first CSS framework
- [shadcn/ui](https://ui.shadcn.com/) - Component library built on Radix UI and Tailwind CSS
- [Radix UI](https://www.radix-ui.com/) - Accessible component primitives
- [Algolia](https://www.algolia.com/) - Site indexing, rapid intra-site search results, and search analytics. [Learn more on how we implement Algolia for site search](./site-search.md).
- Primary implementation: `/src/components/Search/index.ts`
- [Crowdin](https://crowdin.com/) - crowdsourcing for our translation efforts (See "Translation initiative" below)
Expand All @@ -31,8 +33,8 @@
| `/src/data` | General data files importable by components. |
| `/src/hooks` | Custom React hooks. |
| `/src/intl` | Language translation JSON files. |
| `/src/pages/api` | NextJS API Routes (https://nextjs.org/docs/pages/building-your-application/routing/api-routes) |
| `/src/pages` | React components that function as standalone pages. |
| `/app/api` | Next.js API Routes (https://nextjs.org/docs/app/building-your-application/routing/route-handlers) |
| `/app` | Next.js App Router pages and layouts. |
| `/src/scripts`<br>`/src/lib/utils` | Custom utility scripts. |
| `src/@chakra-ui` | Stores `theme.ts` which contains our custom Chakra theme, along with src/@chakra-ui/`semanticTokens.ts` (dark/light mode tokens) and custom Chakra components styles. |
| `src/layouts` | NextJS layouts (https://nextjs.org/docs/pages/building-your-application/routing/pages-and-layouts#with-typescript) that define layouts of different regions of the site. |
| `/src/styles` | Global styles and Tailwind CSS configuration. |
| `/src/layouts` | Next.js layout components used throughout the site. |