From f3a8c41a6d5c20d07078e889815ba479c83f812d Mon Sep 17 00:00:00 2001 From: Olivier Tassinari Date: Mon, 11 Mar 2024 04:50:27 +0100 Subject: [PATCH] [pigment-css][docs] Brand name nonbreaking space (#41438) --- CHANGELOG.md | 2 +- docs/writing-rules/BrandName.yml | 1 + examples/pigment-css-nextjs-ts/README.md | 6 +-- .../pigment-css-nextjs-ts/src/app/page.tsx | 2 +- examples/pigment-css-vite-ts/README.md | 4 +- examples/pigment-css-vite-ts/index.html | 2 +- examples/pigment-css-vite-ts/src/App.tsx | 2 +- packages/pigment-nextjs-plugin/package.json | 2 +- packages/pigment-react/README.md | 46 ++++++++++--------- packages/pigment-react/tests/README.md | 6 +-- 10 files changed, 38 insertions(+), 35 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c392f200b594fe..162d194f580c03 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,7 +11,7 @@ This release was mostly about 🐛 bug fixes and 📚 documentation improvements ### `@pigment-css/react@0.0.1`, `@pigment-css/nextjs-plugin@0.0.1`, `@pigment-css/vite-plugin@0.0.1`, & `@pigment-css/unplugin@0.0.1` -- This is the first public release of our new zero-runtime CSS-in-JS library, Pigment CSS. +- This is the first public release of our new zero-runtime CSS-in-JS library, Pigment CSS. ### `@mui/material@5.15.12` diff --git a/docs/writing-rules/BrandName.yml b/docs/writing-rules/BrandName.yml index bfdb8da88c2725..ac48bba0ddbd88 100644 --- a/docs/writing-rules/BrandName.yml +++ b/docs/writing-rules/BrandName.yml @@ -18,6 +18,7 @@ swap: MUI Toolpad: MUI Toolpad MUI Connect: MUI Connect Stack Overflow: Stack Overflow + Pigment CSS: Pigment CSS # Don't forget to run the following command to generate the package writing-rules.zip file # Vale uses that ZIP file and not the YAML files. # diff --git a/examples/pigment-css-nextjs-ts/README.md b/examples/pigment-css-nextjs-ts/README.md index f4ef7dd52a8ece..63159deba18aae 100644 --- a/examples/pigment-css-nextjs-ts/README.md +++ b/examples/pigment-css-nextjs-ts/README.md @@ -1,6 +1,6 @@ -# Pigment CSS - Next.js App Router with TypeScript example project +# Pigment CSS - Next.js App Router with TypeScript example project -This is a [Next.js](https://nextjs.org/) project bootstrapped using [`create-next-app`](https://github.com/vercel/next.js/tree/HEAD/packages/create-next-app), with TypeScript and Pigment CSS, a zero-runtime CSS-in-JS library, installed. +This is a [Next.js](https://nextjs.org/) project bootstrapped using [`create-next-app`](https://github.com/vercel/next.js/tree/HEAD/packages/create-next-app), with TypeScript and Pigment CSS, a zero-runtime CSS-in-JS library, installed. ## How to use @@ -34,5 +34,5 @@ or: To learn more about this example: -- [Pigment CSS documentation](https://github.com/mui/material-ui/blob/master/packages/pigment-react/README.md) - learn more about Pigment CSS features and APIs. +- [Pigment CSS documentation](https://github.com/mui/material-ui/blob/master/packages/pigment-react/README.md) - learn more about Pigment CSS features and APIs. - [Next.js documentation](https://nextjs.org/docs) - learn about Next.js features and APIs. diff --git a/examples/pigment-css-nextjs-ts/src/app/page.tsx b/examples/pigment-css-nextjs-ts/src/app/page.tsx index 109b5cbdad5f10..e9e18ff5263533 100644 --- a/examples/pigment-css-nextjs-ts/src/app/page.tsx +++ b/examples/pigment-css-nextjs-ts/src/app/page.tsx @@ -85,7 +85,7 @@ export default function Home() { ...theme.applyStyles('dark', { color: '#fff' }), }))}`} > - Pigment CSS + Pigment CSS ({ position: 'absolute', diff --git a/examples/pigment-css-vite-ts/README.md b/examples/pigment-css-vite-ts/README.md index ee0b8e25c330a7..f1154bd1e61d36 100644 --- a/examples/pigment-css-vite-ts/README.md +++ b/examples/pigment-css-vite-ts/README.md @@ -1,4 +1,4 @@ -# Pigment CSS - Vite with TypeScript example project +# Pigment CSS - Vite with TypeScript example project ## How to use @@ -30,5 +30,5 @@ or: To learn more about this example: -- [Pigment CSS documentation](https://github.com/mui/material-ui/blob/master/packages/pigment-react/README.md) - learn more about Pigment CSS features and APIs. +- [Pigment CSS documentation](https://github.com/mui/material-ui/blob/master/packages/pigment-react/README.md) - learn more about Pigment CSS features and APIs. - [Vite documentation](https://vitejs.dev/guide/) - learn about Vite features and APIs. diff --git a/examples/pigment-css-vite-ts/index.html b/examples/pigment-css-vite-ts/index.html index 33cbc8ad392ca2..04c0ee3a1dd977 100644 --- a/examples/pigment-css-vite-ts/index.html +++ b/examples/pigment-css-vite-ts/index.html @@ -4,7 +4,7 @@ - Pigment CSS + Vite + TypeScript + Pigment CSS + Vite + TypeScript
diff --git a/examples/pigment-css-vite-ts/src/App.tsx b/examples/pigment-css-vite-ts/src/App.tsx index cbc7ed15dc3740..4a3b2545b647fc 100644 --- a/examples/pigment-css-vite-ts/src/App.tsx +++ b/examples/pigment-css-vite-ts/src/App.tsx @@ -90,7 +90,7 @@ export default function Home() { ...theme.applyStyles('dark', { color: '#fff' }), }))}`} > - Pigment CSS + Pigment CSS ({ position: 'absolute', diff --git a/packages/pigment-nextjs-plugin/package.json b/packages/pigment-nextjs-plugin/package.json index bf6f89b61f5204..9bd71bd251699a 100644 --- a/packages/pigment-nextjs-plugin/package.json +++ b/packages/pigment-nextjs-plugin/package.json @@ -5,7 +5,7 @@ "module": "build/index.mjs", "types": "build/index.d.ts", "author": "MUI Team", - "description": "Next.js integration for Pigment CSS.", + "description": "Next.js integration for Pigment CSS.", "repository": { "type": "git", "url": "https://github.com/mui/material-ui.git", diff --git a/packages/pigment-react/README.md b/packages/pigment-react/README.md index 19078036889e00..cf0335f0530f20 100644 --- a/packages/pigment-react/README.md +++ b/packages/pigment-react/README.md @@ -1,6 +1,6 @@ -# Pigment CSS +# Pigment CSS -Pigment CSS is a zero-runtime CSS-in-JS library that extracts the colocated styles to their own CSS files at build time. +Pigment CSS is a zero-runtime CSS-in-JS library that extracts the colocated styles to their own CSS files at build time. - [Getting started](#getting-started) - [Why this project exists?](#why-choose-pigment-css) @@ -24,20 +24,21 @@ Pigment CSS is a zero-runtime CSS-in-JS library that extracts the colocated styl ## Getting started -Pigment CSS supports Next.js and Vite with support for more bundlers in future. You must install the corresponding plugin, as shown below. +Pigment CSS supports Next.js and Vite with support for more bundlers in the future. +You must install the corresponding plugin, as shown below. -### Why choose Pigment CSS +### Why choose Pigment CSS Thanks to recent advancements in CSS (like CSS variables and `color-mix()`), "traditional" CSS-in-JS solutions that process styles at runtime are no longer required for unlocking features like color transformations and theme variables which are necessary for maintaining a sophisticated design system. -Pigment CSS addresses the needs of the modern React developer by providing a zero-runtime CSS-in-JS styling solution as a successor to tools like Emotion and styled-components. +Pigment CSS addresses the needs of the modern React developer by providing a zero-runtime CSS-in-JS styling solution as a successor to tools like Emotion and styled-components. -Compared to its predecessors, Pigment CSS offers improved DX and runtime performance (though at the cost of increased build time) while also being compatible with React Server Components. -Pigment CSS is built on top of [WyW-in-JS](https://wyw-in-js.dev/), enabling us to provide the smoothest possible experience for Material UI users when migrating from Emotion in v5 to Pigment in v6. +Compared to its predecessors, Pigment CSS offers improved DX and runtime performance (though at the cost of increased build time) while also being compatible with React Server Components. +Pigment CSS is built on top of [WyW-in-JS](https://wyw-in-js.dev/), enabling us to provide the smoothest possible experience for Material UI users when migrating from Emotion in v5 to Pigment CSS in v6. ### Start with Next.js -Use the following commands to create a new Next.js project with Pigment CSS set up: +Use the following commands to create a new Next.js project with Pigment CSS set up: ```bash curl https://codeload.github.com/mui/material-ui/tar.gz/master | tar -xz --strip=2 material-ui-master/examples/pigment-css-nextjs-ts @@ -83,7 +84,7 @@ Finally, import the stylesheet in the root `layout.tsx` file: ### Start with Vite -Use the following commands to create a new Vite project with Pigment CSS set up: +Use the following commands to create a new Vite project with Pigment CSS set up: ```bash curl https://codeload.github.com/mui/material-ui/tar.gz/master | tar -xz --strip=2 material-ui-master/examples/pigment-css-vite-ts @@ -130,7 +131,7 @@ Finally, import the stylesheet in the root `main.tsx` file: ## Basic usage -**You must configure Pigment CSS with [Next.js](#nextjs) or [Vite](#vite) first.** +**You must configure Pigment CSS with [Next.js](#nextjs) or [Vite](#vite) first.** ### Creating styles @@ -186,10 +187,10 @@ function App() { } ``` -The Pigment CSS library differs from "standard" runtime CSS-in-JS libraries in a few ways: +The Pigment CSS library differs from "standard" runtime CSS-in-JS libraries in a few ways: 1. You never get direct access to props in your styled declarations. This is because prop values are only available at runtime, but the CSS is extracted at build time. See [Styling based on runtime values](#styling-based-on-runtime-values) for a workaround. -2. Your styles must be declarative, and must account for all combinations of props that you want to style. +2. Your styles must be declarative and must account for all combinations of props that you want to style. 3. The theme lets you declare CSS tokens that become part of the CSS bundle after the build. Any other values and methods that it might have are only available during build time—not at runtime. This leads to smaller bundle sizes. #### Styling based on props @@ -296,7 +297,7 @@ const Button = styled('button')({ #### Styling based on runtime values -> 💡 This approach is recommended when the value of a prop is **unknown** ahead of time or possibly unlimited values, e.g. styling based on the user's input. +> 💡 This approach is recommended when the value of a prop is **unknown** ahead of time or possibly unlimited values, for example styling based on the user's input. Use a callback function as a value to create a dynamic style for the specific CSS property: @@ -306,7 +307,7 @@ const Heading = styled('h1')({ }); ``` -Pigment CSS will replace the callback with a CSS variable and inject the value through inline style. This makes it possible to create a static CSS file while still allowing dynamic styles. +Pigment CSS will replace the callback with a CSS variable and inject the value through inline style. This makes it possible to create a static CSS file while still allowing dynamic styles. ```css .Heading_class_akjsdfb { @@ -457,7 +458,7 @@ const Heading = styled('h1')(({ theme }) => ({ #### CSS variables support -Pigment CSS can generate CSS variables from the theme values when you wrap your theme with `extendTheme` utility. For example, in a `next.config.js` file: +Pigment CSS can generate CSS variables from the theme values when you wrap your theme with `extendTheme` utility. For example, in a `next.config.js` file: ```js const { withPigment, extendTheme } = require('@pigment-css/nextjs-plugin'); @@ -501,7 +502,7 @@ console.log(theme.vars.colors.primary); // 'var(--colors-primary)' Some tokens, especially color-related tokens, can have different values for different scenarios. For example in a daylight condition, the background color might be white, but in a dark condition, it might be black. -The `extendTheme` utility lets you define theme with a special `colorSchemes` key: +The `extendTheme` utility lets you define a theme with a special `colorSchemes` key: ```jsx extendTheme({ @@ -558,7 +559,8 @@ function App() { #### Styling based on color scheme -The `extendTheme` utility attach a function called `applyStyles` to the theme object. It receives a color scheme as the first argument followed by a style object. It will return a proper CSS selector based on the theme configuration. +The `extendTheme` utility attaches a function called `applyStyles` to the theme object. It receives a color scheme as the first argument followed by a style object. +It will return a proper CSS selector based on the theme configuration. ```jsx const Heading = styled('h1')(({ theme }) => ({ @@ -618,9 +620,9 @@ declare module '@pigment-css/react/theme' { Emotion and styled-components are runtime CSS-in-JS libraries. What you write in your styles is what you get in the final bundle, which means the styles can be as dynamic as you want with bundle size and performance overhead trade-offs. -On the other hand, Pigment CSS extracts CSS at build time and replaces the JS code with hashed class names and some CSS variables. This means that it has to know all of the styles to be extracted ahead of time, so there are rules and limitations that you need to be aware of when using JavaScript callbacks or variables in Pigment CSS's APIs. +On the other hand, Pigment CSS extracts CSS at build time and replaces the JS code with hashed class names and some CSS variables. This means that it has to know all of the styles to be extracted ahead of time, so there are rules and limitations that you need to be aware of when using JavaScript callbacks or variables in Pigment CSS's APIs. -Here are some common patterns and how to achieve them with Pigment CSS: +Here are some common patterns and how to achieve them with Pigment CSS: 1. **Fixed set of styles** @@ -629,7 +631,7 @@ In Emotion or styled-components, you can use props to create styles conditionall ```js const Flex = styled('div')((props) => ({ display: 'flex', - ...(props.vertical // ❌ Pigment CSS will throw an error + ...(props.vertical // ❌ Pigment CSS will throw an error ? { flexDirection: 'column', paddingBlock: '1rem', @@ -640,7 +642,7 @@ const Flex = styled('div')((props) => ({ })); ``` -But in Pigment CSS, you need to define all of the styles ahead of time using the `variants` key: +But in Pigment CSS, you need to define all of the styles ahead of time using the `variants` key: ```js const Flex = styled('div')((props) => ({ @@ -691,7 +693,7 @@ function App() { } ``` -However, in Pigment CSS with the same code as above, all instances will have the same styles and won't change between renders because the styles are extracted at build time. +However, in Pigment CSS with the same code as above, all instances will have the same styles and won't change between renders because the styles are extracted at build time. To achieve the same result, you need to move the dynamic logic to props and pass the value to CSS variables instead: diff --git a/packages/pigment-react/tests/README.md b/packages/pigment-react/tests/README.md index 5da4275ebf7d59..728d83d3822f49 100644 --- a/packages/pigment-react/tests/README.md +++ b/packages/pigment-react/tests/README.md @@ -1,4 +1,4 @@ -# Pigment CSS testing +# Pigment CSS testing ## Folder structure @@ -24,11 +24,11 @@ pnpm nx run @pigment-css/react:test:update ## Adding new tests -Each folder inside `tests` is a Pigment CSS feature. To add a new test, create a new folder with the feature name and add a new test file with the `.test.js` extension. Inside the test file, import the fixtures and run the tests. +Each folder inside `tests` is a Pigment CSS feature. To add a new test, create a new folder with the feature name and add a new test file with the `.test.js` extension. Inside the test file, import the fixtures and run the tests. ## Adding new fixtures -Create a new file name with `[name].input.js` and add `styled`, `css` or other Pigment CSS calls into the file. +Create a new file name with `[name].input.js` and add `styled`, `css` or other Pigment CSS calls into the file. The first time you run the tests, the output files will be created automatically. Then check the output files to make sure they are correct.