Skip to content

Commit 0eb4011

Browse files
committed
Update documentation and redirects to standardize references to component classes, enhancing clarity and consistency across guides
1 parent 1931e98 commit 0eb4011

18 files changed

Lines changed: 68 additions & 253 deletions

File tree

‎site/app/[locale]/guide/cascade-layers/components/LayersDefault.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ export default () => {
2929
</tr>
3030
<tr>
3131
<th>Components</th>
32-
<td>Where the used <Link href="/guide/reusing-styles#components">component classes</Link> are generated.</td>
32+
<td>Where the used <Link href="/guide/reusing-styles#component-classes">component classes</Link> are generated.</td>
3333
<td className="white-space:nowrap"><code>{'@layer components { … }'}</code></td>
3434
</tr>
3535
<tr>

‎site/app/[locale]/guide/code-linting/content.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ In the past, you added utility classes to your templates unsafely, lacking the c
3434
This is helpful if you make a typo or are unfamiliar with Master CSS syntax!
3535

3636
### Disallow unknown classes
37-
You can also restrict teams to using [theme](/guide/theme) and [component classes](/guide/reusing-styles#components) instead of defining classes through traditional `html <style>` or CSS files.
37+
You can also restrict teams to using [theme](/guide/theme) and [component classes](/guide/reusing-styles#component-classes) instead of defining classes through traditional `html <style>` or CSS files.
3838

3939
(i) Based on syntax error checking, you can [disallow unknown classes](/reference/eslint#class-validation).
4040
<Image className="aspect:2/1 r:lg max-w:screen-xs w:full" src={require('~/site/public/disallow-unknown-class.webp').default} alt="Disallow unknown classes" unoptimized />
@@ -48,7 +48,7 @@ You can also restrict teams to using [theme](/guide/theme) and [component classe
4848
```html
4949
<button class="inline-flex px:md">…</button>
5050
```
51-
(o) Or create the custom style `btn` using [component classes](/guide/reusing-styles#components) in the project CSS entry.
51+
(o) Or create the custom style `btn` using [component classes](/guide/reusing-styles#component-classes) in the project CSS entry.
5252
```css name=index.css
5353
@layer components {
5454
.btn {
Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { permanentRedirect } from 'next/navigation'
22

33
export default function Page() {
4-
permanentRedirect('/guide/reusing-styles#components')
4+
permanentRedirect('/guide/reusing-styles#component-classes')
55
}

‎site/app/[locale]/guide/introduction/components/Comparisons.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -156,7 +156,7 @@ export const bootstrap = brands['bootstrap']
156156
<td><InlineBad /></td>
157157
</tr>
158158
<tr>
159-
<th>[Component classes](/guide/reusing-styles#components)</th>
159+
<th>[Component classes](/guide/reusing-styles#component-classes)</th>
160160
<td><InlineGood /></td>
161161
<td><InlineWarn />`@apply`</td>
162162
<td><InlineBad />Predefined</td>

‎site/app/[locale]/guide/introduction/content.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ Think of each class as a small CSS statement:
3131

3232
Under the hood, Master CSS generates real CSS rules, adds [vendor prefixes](/guide/compatibility#vendor-prefixes), places rules in predictable [cascade layers](/guide/cascade-layers), and [orders CSS rules](#smart-rule-ordering) for you. You keep the styling decision close to the element, while the engine handles the CSS output.
3333

34-
For one-off interface work, you can stay in markup. When a value, selector, condition, primitive, native rule, or repeated pattern becomes part of your product vocabulary, move it into the [project CSS entry](/guide/theme) as a token, selector token, at token, utility, native composed rule, or [component class](/guide/reusing-styles#components).
34+
For one-off interface work, you can stay in markup. When a value, selector, condition, primitive, native rule, or repeated pattern becomes part of your product vocabulary, move it into the [project CSS entry](/guide/theme) as a token, selector token, at token, utility, native composed rule, or [component class](/guide/reusing-styles#component-classes).
3535

3636
### Readable structured syntax
3737
Master CSS is not trying to put a second `style=""` attribute inside `class=""`. The syntax is CSS-like, but it is designed to be shorter, composable, and easier for tools to understand.
@@ -292,7 +292,7 @@ Use semantic tokens and components when:
292292
- The team has a design-system decision worth naming.
293293
- Consumers should use the concept without knowing every underlying utility.
294294

295-
Assuming the card has become reusable, define it as a [component class](/guide/reusing-styles#components) in the project CSS entry:
295+
Assuming the card has become reusable, define it as a [component class](/guide/reusing-styles#component-classes) in the project CSS entry:
296296

297297
```css name=index.css
298298
@layer components {
@@ -457,7 +457,7 @@ If you are new to Master CSS, continue in this order:
457457
2. [Style declarations](/guide/style-declarations) to learn the class syntax in detail.
458458
3. [State selectors](/guide/state-selectors), [responsive design](/guide/responsive-design), and [conditional queries](/guide/conditional-queries) to control when styles apply.
459459
4. [Rendering modes](/guide/rendering-modes) to choose runtime rendering, static rendering, or progressive rendering.
460-
5. [Design tokens](/guide/design-tokens), [theme](/guide/theme), and [component classes](/guide/reusing-styles#components) when your project needs shared vocabulary.
460+
5. [Design tokens](/guide/design-tokens), [theme](/guide/theme), and [component classes](/guide/reusing-styles#component-classes) when your project needs shared vocabulary.
461461

462462
---
463463

‎site/app/[locale]/guide/migration/tailwindcss/content.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -182,7 +182,7 @@ module.exports = {
182182

183183
## Strategies
184184
### Alternative to `@apply`
185-
Use [component classes](/guide/reusing-styles#components) and `@compose` to abstract styles instead of Tailwind's `@apply`.
185+
Use [component classes](/guide/reusing-styles#component-classes) and `@compose` to abstract styles instead of Tailwind's `@apply`.
186186
```css name=main.css
187187
@tailwind base;
188188
@tailwind;

‎site/app/[locale]/guide/migration/v1/content.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -103,7 +103,7 @@ Apply the style:
103103
```html
104104
<button class="btn"></button>
105105
```
106-
To learn more, check out [component classes](/guide/reusing-styles#components).
106+
To learn more, check out [component classes](/guide/reusing-styles#component-classes).
107107

108108
### Merging media queries
109109
Deprecate extended `breakpoints` and `queries` ​​in favor of screen variables and custom at tokens in the project CSS entry.

‎site/app/[locale]/guide/reusing-styles/content.mdx‎

Lines changed: 45 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11
## Overview [sr-only]
22
Reusable styling starts with a decision, not a file. Keep local choices in markup, move shared values into theme tokens, and define component classes only when a repeated pattern has product meaning.
33

4-
Writing `.btn` at the top level of a stylesheet creates a normal CSS rule. It can use `@compose` and `@at`, but it is still emitted by that stylesheet as native CSS. Writing `.btn` in top-level `@layer components` defines a Master CSS component class instead: it is generated on demand when `btn` is used in markup, scanned from source, or composed by another CSS-defined style.
4+
Writing `.btn` at the top level of a stylesheet creates a normal CSS rule. Writing `.btn` in top-level `@layer components` defines an on-demand component class. Writing `.flow` in top-level `@layer utilities` defines an on-demand utility class. All three can use `@compose` and `@at`, but they serve different ownership needs.
55

66
---
77

8-
## Start with utilities
8+
## Reuse decisions
9+
### Start with utilities
910
Use utility classes when the style belongs to one element, one state, or one local layout decision. This keeps the relationship between markup and style explicit while the pattern is still changing.
1011

1112
```html
@@ -16,9 +17,7 @@ Use utility classes when the style belongs to one element, one state, or one loc
1617

1718
Do not abstract just to shorten a class list. Abstract when the name improves the product vocabulary: `btn`, `card`, `field`, `toolbar`, `empty-state`, or another role that appears across the interface.
1819

19-
---
20-
21-
## Move shared values into the theme
20+
### Move shared values into the theme
2221
When the repeated part is a value, make it a token instead of a class. Tokens keep markup semantic while still letting each component choose its own structure.
2322

2423
```css name=index.css
@@ -39,10 +38,39 @@ When the repeated part is a value, make it a token instead of a class. Tokens ke
3938

4039
Use [Customizing your theme](/guide/theme) when the reusable part is color, spacing, typography, radius, shadow, motion, screens, or mode-specific values.
4140

41+
### Create custom utilities
42+
Use top-level `@layer utilities` when your design system needs a reusable primitive that is still lower-level than a product component. Good utility names describe a styling capability, not a UI role.
43+
44+
```css name=index.css
45+
@layer utilities {
46+
.flow {
47+
@compose "grid gap:md";
48+
}
49+
50+
.content-auto {
51+
content-visibility: auto;
52+
contain-intrinsic-size: auto 32rem;
53+
}
54+
55+
.print-hidden {
56+
@at print {
57+
display: none;
58+
}
59+
}
60+
}
61+
```
62+
63+
```html
64+
<!-- @MARK flow --><!-- @MARK content-auto --><!-- @MARK print-hidden -->
65+
<section class="flow content-auto print-hidden">...</section>
66+
```
67+
68+
Custom utility definitions are converted into config and generated only when the class appears in markup, is scanned from source, or is composed by another CSS-defined style. Use custom utilities for reusable primitives such as layout helpers, rendering hints, or print behavior. Use component classes when the name describes a product UI role such as `.btn`, `.card`, or `.field`.
69+
4270
---
4371

44-
## Create component classes
45-
<span id="components" />
72+
## Component classes
73+
### Define a component class
4674
Use a component class when a repeated class list becomes a reusable UI pattern. Define components in top-level `@layer components`, put Master CSS classes in `@compose`, and write native declarations directly in the rule.
4775

4876
```css name=index.css
@@ -96,7 +124,7 @@ You can still apply component classes alongside conditional utility classes when
96124

97125
---
98126

99-
## Add states and conditions
127+
### Add states and conditions
100128
Put selector states in nested selectors and conditional variants in `@at` blocks. This keeps the component definition readable and keeps the markup semantic.
101129

102130
```css name=index.css
@@ -133,7 +161,7 @@ Equivalent markup stays short:
133161

134162
---
135163

136-
## Keep variants composable
164+
### Keep variants composable
137165
Avoid hiding every option behind a new component. Give each component class one responsibility, then combine it with tokens, utilities, or smaller component classes.
138166

139167
```css name=styles/button.css
@@ -202,7 +230,7 @@ If one class tries to own size, color, shape, layout, and interaction variants,
202230

203231
---
204232

205-
## Build shared structures
233+
### Build shared structures
206234
Create explicit classes for each meaningful part of a repeated structure. Avoid relying on descendant selectors when separate class names make the output easier to trace.
207235

208236
```css name=index.css
@@ -252,7 +280,8 @@ In this example, `size:12x` is generated for `.empty-state::before`, not for `.e
252280

253281
---
254282

255-
## Use native CSS when output should be native
283+
## Native CSS and files
284+
### Use native CSS when output should be native
256285
`@compose` is not limited to component definitions. It can also be used in native style rules. The difference is output ownership:
257286

258287
- `@layer components`, `@layer preset`, and `@layer utilities` create on-demand managed class definitions.
@@ -279,7 +308,7 @@ Use native CSS when the selector is part of a stylesheet surface you already shi
279308

280309
---
281310

282-
## Organize component files
311+
### Organize component files
283312
Split component definitions only when it helps ownership. Local CSS imports from the project CSS entry are compiled into one graph.
284313

285314
<ExplorerView>
@@ -337,7 +366,8 @@ Split component definitions only when it helps ownership. Local CSS imports from
337366

338367
---
339368

340-
## Component rules
369+
## Rules and summary
370+
### Component rules
341371
- Put component definitions in top-level `@layer components`; use `@layer preset` only when a definition intentionally belongs to the earlier preset layer.
342372
- Component selectors must start with a single class selector such as `.btn`, `.card`, or `.field::before`.
343373
- `@compose` is valid inside managed class definitions and native style rules.
@@ -346,11 +376,10 @@ Split component definitions only when it helps ownership. Local CSS imports from
346376
- Standard HTML tag selectors such as `body` or `html` are not valid inside managed layer definitions.
347377
- Utilities still win over components because `@master/css/base.css` declares `@layer theme, base, preset, components, utilities;`.
348378

349-
---
350-
351-
## Summary
379+
### Summary
352380
- Keep local styling in markup until a pattern proves it should be shared.
353381
- Move shared values into theme tokens before creating new classes.
382+
- Use custom utilities for reusable primitives that are not product UI roles.
354383
- Use component classes for reusable UI roles, not for every repeated declaration.
355384
- Keep component classes small enough to combine with tokens, utilities, states, and conditions.
356385
- Use native CSS when the selector belongs to a stylesheet you already ship; use managed component classes when the class should be generated on demand.

‎site/app/[locale]/guide/style-declarations/components/UnitConversion.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,6 @@ For many size-related utilities, you can think in pixels while Master CSS emits
1919

2020
The unitless `48` is interpreted as pixels for `font` and converted to `3rem` when CSS is generated.
2121

22-
Master CSS defines [practical unit and conversion behavior](/guide/utilities#syntax-reference) by utility. Many size values convert from pixels to `rem`, while other properties keep or infer a different unit.
22+
Master CSS defines practical unit and conversion behavior by utility. Many size values convert from pixels to `rem`, while other properties keep or infer a different unit.
2323

2424
Use explicit units when you need to preserve a value exactly as written.

‎site/app/[locale]/guide/style-declarations/components/Utilities.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,12 +19,12 @@ The most explicit form is a native property name plus a value. It is easy to und
1919
{code2}
2020
</Code>
2121

22-
When the meaning is still clear without the property name, Master CSS can use the value itself as a [default utility](/guide/utilities#default-reference). For example, `mcss display:block` becomes `mcss block`, and `mcss position:absolute` becomes `mcss abs`.
22+
When the meaning is still clear without the property name, Master CSS can use the value itself as a default utility. For example, `mcss display:block` becomes `mcss block`, and `mcss position:absolute` becomes `mcss abs`.
2323

2424
Not every value becomes a utility. Master CSS avoids shortcuts when the result would be ambiguous. For example, `mcss font-weight:lighter` is not reduced to `mcss lighter`, because `lighter` could also sound like a color or brightness change.
2525

2626
Several utilities are also higher-level conveniences, such as [screen readers](/reference/screen-readers) and [text size](/reference/text-size) classes that include line-height decisions.
2727

2828
Use utilities when the shorter class still communicates the intended CSS. Keep the explicit property form when the shortcut would make a reader stop and guess.
2929

30-
To learn more about customizing utilities, check out the [utilities](/guide/utilities) documentation.
30+
To learn more about project-specific utility classes, see [custom utilities](/guide/reusing-styles#create-custom-utilities).

0 commit comments

Comments
 (0)