diff --git a/CLAUDE.md b/CLAUDE.md index 7a568bf26a0..4e3402901a9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 diff --git a/docs/applying-storybook.md b/docs/applying-storybook.md index 49b3ea8c348..fc47cbf8867 100644 --- a/docs/applying-storybook.md +++ b/docs/applying-storybook.md @@ -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. diff --git a/docs/best-practices.md b/docs/best-practices.md index 7542e54eaf8..fdb60a580a5 100644 --- a/docs/best-practices.md +++ b/docs/best-practices.md @@ -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 - -``` - -Center things using the `
` component +Use standard HTML elements with Tailwind classes for layouts: ```tsx -
-``` +// Flexbox layouts +
+
-- Group buttons using `` or `` +// Grid layouts +
-```tsx - - - - - -// or - - - - +// Centering +
``` -- 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 - +import { Button } from "@/components/ui/button" + + ``` -- Theme colors +### Colors and Theming + +Use CSS custom properties defined in the design system: ```tsx - +
+
``` -> 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. @@ -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" diff --git a/docs/code-conventions.md b/docs/code-conventions.md index 7f7e87c971c..635086abb00 100644 --- a/docs/code-conventions.md +++ b/docs/code-conventions.md @@ -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( +const Component = React.forwardRef( ({ title, label, ...props }, ref) => { - // Component code + return ( +
+ {/* Component code */} +
+ ) } ) ``` diff --git a/docs/stack.md b/docs/stack.md index 6d3b4107490..dfa41d6de0b 100644 --- a/docs/stack.md +++ b/docs/stack.md @@ -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) @@ -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`
`/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. |