You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 0eb4011
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: site/app/[locale]/guide/code-linting/content.mdx
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -34,7 +34,7 @@ In the past, you added utility classes to your templates unsafely, lacking the c
34
34
This is helpful if you make a typo or are unfamiliar with Master CSS syntax!
35
35
36
36
### 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.
38
38
39
39
(i) Based on syntax error checking, you can [disallow unknown classes](/reference/eslint#class-validation).
Copy file name to clipboardExpand all lines: site/app/[locale]/guide/introduction/content.mdx
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -31,7 +31,7 @@ Think of each class as a small CSS statement:
31
31
32
32
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.
33
33
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).
35
35
36
36
### Readable structured syntax
37
37
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:
292
292
- The team has a design-system decision worth naming.
293
293
- Consumers should use the concept without knowing every underlying utility.
294
294
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:
296
296
297
297
```css name=index.css
298
298
@layer components {
@@ -457,7 +457,7 @@ If you are new to Master CSS, continue in this order:
457
457
2.[Style declarations](/guide/style-declarations) to learn the class syntax in detail.
458
458
3.[State selectors](/guide/state-selectors), [responsive design](/guide/responsive-design), and [conditional queries](/guide/conditional-queries) to control when styles apply.
459
459
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.
Copy file name to clipboardExpand all lines: site/app/[locale]/guide/reusing-styles/content.mdx
+45-16Lines changed: 45 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,11 +1,12 @@
1
1
## Overview [sr-only]
2
2
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.
3
3
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.
5
5
6
6
---
7
7
8
-
## Start with utilities
8
+
## Reuse decisions
9
+
### Start with utilities
9
10
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.
10
11
11
12
```html
@@ -16,9 +17,7 @@ Use utility classes when the style belongs to one element, one state, or one loc
16
17
17
18
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.
18
19
19
-
---
20
-
21
-
## Move shared values into the theme
20
+
### Move shared values into the theme
22
21
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.
23
22
24
23
```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
39
38
40
39
Use [Customizing your theme](/guide/theme) when the reusable part is color, spacing, typography, radius, shadow, motion, screens, or mode-specific values.
41
40
41
+
### Create custom utilities
42
+
Usetop-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.
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
+
42
70
---
43
71
44
-
## Create component classes
45
-
<span id="components" />
72
+
## Component classes
73
+
### Define a component class
46
74
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.
47
75
48
76
```css name=index.css
@@ -96,7 +124,7 @@ You can still apply component classes alongside conditional utility classes when
96
124
97
125
---
98
126
99
-
## Add states and conditions
127
+
###Add states and conditions
100
128
Put selector states in nested selectors and conditional variants in `@at` blocks. This keeps the component definition readable and keeps the markup semantic.
Avoid hiding every option behind a new component. Give each component class one responsibility, then combine it with tokens, utilities, or smaller component classes.
138
166
139
167
```css name=styles/button.css
@@ -202,7 +230,7 @@ If one class tries to own size, color, shape, layout, and interaction variants,
202
230
203
231
---
204
232
205
-
## Build shared structures
233
+
###Build shared structures
206
234
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.
207
235
208
236
```css name=index.css
@@ -252,7 +280,8 @@ In this example, `size:12x` is generated for `.empty-state::before`, not for `.e
252
280
253
281
---
254
282
255
-
## Use native CSS when output should be native
283
+
## Native CSS and files
284
+
### Use native CSS when output should be native
256
285
`@compose` is not limited to component definitions. It can also be used in native style rules. The difference is output ownership:
257
286
258
287
-`@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
279
308
280
309
---
281
310
282
-
## Organize component files
311
+
###Organize component files
283
312
Split component definitions only when it helps ownership. Local CSS imports from the project CSS entry are compiled into one graph.
284
313
285
314
<ExplorerView>
@@ -337,7 +366,8 @@ Split component definitions only when it helps ownership. Local CSS imports from
337
366
338
367
---
339
368
340
-
## Component rules
369
+
## Rules and summary
370
+
### Component rules
341
371
- Put component definitions in top-level `@layer components`; use `@layer preset` only when a definition intentionally belongs to the earlier preset layer.
342
372
- Component selectors must start with a single class selector such as `.btn`, `.card`, or `.field::before`.
343
373
- `@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
346
376
- Standard HTML tag selectors such as `body` or `html` are not valid inside managed layer definitions.
347
377
- Utilities still win over components because `@master/css/base.css` declares `@layer theme, base, preset, components, utilities;`.
348
378
349
-
---
350
-
351
-
## Summary
379
+
### Summary
352
380
- Keep local styling in markup until a pattern proves it should be shared.
353
381
- Move shared values into theme tokens before creating new classes.
382
+
- Use custom utilities for reusable primitives that are not product UI roles.
354
383
- Use component classes for reusable UI roles, not for every repeated declaration.
355
384
- Keep component classes small enough to combine with tokens, utilities, states, and conditions.
356
385
- 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.
Copy file name to clipboardExpand all lines: site/app/[locale]/guide/style-declarations/components/UnitConversion.mdx
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,6 +19,6 @@ For many size-related utilities, you can think in pixels while Master CSS emits
19
19
20
20
The unitless `48` is interpreted as pixels for `font` and converted to `3rem` when CSS is generated.
21
21
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.
23
23
24
24
Use explicit units when you need to preserve a value exactly as written.
Copy file name to clipboardExpand all lines: site/app/[locale]/guide/style-declarations/components/Utilities.mdx
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,12 +19,12 @@ The most explicit form is a native property name plus a value. It is easy to und
19
19
{code2}
20
20
</Code>
21
21
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`.
23
23
24
24
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.
25
25
26
26
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.
27
27
28
28
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.
29
29
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