Skip to content

06_property-order-quick-reference.md

Latest commit

 

History

History
118 lines (93 loc) · 7.24 KB

06_property-order-quick-reference.md

File metadata and controls

118 lines (93 loc) · 7.24 KB

CONTRIBUTOR-DOCS / Style guide / 2nd-Gen CSS / Property order quick reference

Property order quick reference

In this doc

Use this guide when writing or reviewing component CSS. Consistent property order makes stylesheets easier to scan and reduces merge conflicts. This order is enforced via stylelint-order and the property groups defined in linters/stylelint-property-order.js. The table below is a condensed summary — see that file for the full list.

For full context, see Component CSS.

Why property order matters

  • Consistency: Everyone can find properties quickly
  • Readability: Related properties stay together
  • Maintainability: Changes are easier to spot in code review

Expected property order

This is the expected order as enforced by stylelint-order:

# Category Common properties
1 Display box-sizing, display, visibility
2 Position position, inset, top, right, bottom, left, z-index
3 Flex/Grid flex, flex-grow, flex-shrink, flex-basis, flex-direction, flex-wrap, grid, grid-template-*, grid-auto-*
4 Alignment gap, place-content, place-items, place-self, align-items, align-self, justify-content, justify-items, order
5 Dimensions inline-size, block-size, width, height, min-*, max-*, aspect-ratio
6 Spacing padding, padding-*, margin, margin-*
7 Typography font, font-family, font-size, font-style, font-weight, line-height, color, text-align, text-transform, letter-spacing, white-space
8 Decoration background, background-*, border, border-*, border-radius, box-shadow
9 Overflow overflow, text-overflow
10 User interface appearance, pointer-events, cursor, user-select, outline, outline-*
11 Color adjustment color-scheme, forced-color-adjust
12 Generated content content, quotes
13 SVG fill, stroke, stroke-width, stroke-dasharray, stroke-dashoffset
14 Effects opacity, filter, backdrop-filter
15 Transforms transform, transform-origin
16 Transitions/Animations transition, animation, will-change

Example from Badge

From badge.css:

.swc-Badge {
  /* Custom properties first (definitions) */
  --_swc-badge-border-width: token("border-width-200");
  --_swc-badge-padding-block: var(--swc-badge-padding-block, token("component-padding-vertical-100"));
  --_swc-badge-padding-inline-start: var(--swc-badge-padding-inline-start, var(--swc-badge-padding-inline, token("component-edge-to-text-100")));
  --_swc-badge-padding-inline: var(--swc-badge-padding-inline, token("component-edge-to-text-100"));
  --_swc-badge-line-height: var(--swc-badge-line-height, token("line-height-font-size-100"));

  /* Display */
  display: inline-flex;
  /* Alignment */
  gap: var(--swc-badge-gap, token("text-to-visual-100"));
  align-items: center;
  /* Dimensions */
  min-block-size: var(--swc-badge-height, token("component-height-100"));
  /* Spacing */
  padding-block: calc(var(--_swc-badge-padding-block) - var(--_swc-badge-border-width));
  padding-inline-start: calc(var(--_swc-badge-padding-inline-start) - var(--_swc-badge-border-width));
  padding-inline-end: calc(var(--_swc-badge-padding-inline) - var(--_swc-badge-border-width));
  /* Typography */
  color: var(--swc-badge-label-icon-color, token("white"));
  /* Decoration */
  background: var(--swc-badge-background-color, token("neutral-subdued-background-color-default"));
  border: var(--_swc-badge-border-width) solid var(--swc-badge-border-color, transparent);
  border-radius: var(--swc-badge-corner-radius, token("corner-radius-medium-size-medium"));
  /* User interface */
  cursor: default;
}

Example from Status Light

From status-light.css:

.swc-StatusLight::before {
  /* Custom properties */
  --_swc-status-light-dot-size: var(--swc-status-light-dot-size, token("status-light-dot-size-medium"));
  /* Flex/Grid */
  flex-grow: 0;
  flex-shrink: 0;
  /* Dimensions */
  inline-size: var(--_swc-status-light-dot-size);
  block-size: var(--_swc-status-light-dot-size);
  /* Spacing */
  margin-block-start: calc(var(--_swc-status-light-top-to-dot) - var(--_swc-status-light-padding-block));
  /* Decoration */
  background-color: var(--swc-status-light-dot-color, token("neutral-visual-color"));
  border-radius: token("corner-radius-full");
  /* Generated content */
  content: "";
}

Reference implementations: Badge · Status Light