Menu
CSS architecture, best practices, and patterns for WordPress projects. Covers ITCSS methodology, accessibility, specificity management, naming conventions, and modern CSS features.
| name | 10up-css |
| description | CSS architecture, best practices, and patterns for WordPress projects. Covers ITCSS methodology, accessibility, specificity management, naming conventions, and modern CSS features. |
| license | MIT |
| compatibility | Modern browsers, WordPress 6.0+ |
| globs | ["**/*.css","**/*.scss","**/*.sass","**/*.pcss","postcss.config.js"] |
| metadata | {"author":"10up","version":"1.0"} |
This skill provides comprehensive CSS authoring guidelines following 10up standards for WordPress development.
Assume existing conventions exist for valid reasons. Learn the codebase before suggesting changes. Only propose modifications when current systems create genuine problems—inconsistency, scaling issues, or errors.
When designing new CSS systems, capture folder layout, naming conventions, tooling decisions, and rationales. Store documentation in /decisions/ directories within repositories.
Build components assuming no control over content. Test against extreme scenarios:
Prioritize mobile layouts in implementation. Style projects as if desktop doesn't exist initially.
Implementation strategy:
auto-fit, clamp()) to create inherently responsive layoutsscrolling over carousels or dropdowns when appropriateWatch for:
Set box-sizing: border-box globally at project start:
*,
*::before,
*::after {
box-sizing: border-box;
}
:where(body) {
margin: 0;
}
Establish foundational styles using :where() for zero specificity. Avoid opinionated defaults like text-align: center that require constant overrides.
Target range: 0,1,0 to 0,2,1 maximum.
Rules:
a.button → .button):where() for bare element styles[id="drawer"] if needed)!important for exceptional cases only/* Use :where() for zero specificity on base elements */
:where(h1, h2, h3, h4, h5, h6) {
margin-block: 0;
}
/* Nesting pseudo-classes for state is acceptable */
.button {
&:hover {
/* styles here */
}
}
/* Keep child selectors flat, not nested */
.button__icon {
/* styles here */
}
Use logical properties instead of broad shorthands:
/* Do this */
.element {
margin-inline: auto;
background-color: var(--color-primary);
}
/* Avoid */
.element {
margin: 0 auto; /* Sets unintended values */
background: var(--color-primary); /* Resets other background properties */
}
Target elements precisely. Instead of global selectors affecting all elements:
/* Avoid broad selectors */
a { color: blue; }
/* Use scoped selectors */
.entry-content :is(h1, h2, h3, p, li) > a {
color: var(--color-link);
}
Never add margins to reusable components. Margins lock components into specific contexts.
/* Avoid */
.card {
margin-block: 1.5rem;
}
/* Do this - manage spacing at container level */
.card-grid {
display: grid;
row-gap: 1.5rem;
}
Apply margins in one direction only (preferably upward):
.component > * + * {
margin-top: 1.5em;
}
Prioritize intrinsic solutions:
/* Use clamp() for fluid values */
.heading {
font-size: clamp(1.5rem, 4vw, 3rem);
}
/* Use CSS Grid for flexible layouts */
.grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(min(300px, 100%), 1fr));
gap: 1.5rem;
}
Use rem, em, % over fixed pixels. Media queries should be fallbacks for cases where intrinsic solutions won't work.
.element {
height: 100vh; /* widely supported */
height: 100dvh; /* newer unit */
}
@supports for feature detection:.site {
min-height: 100dvh;
}
@supports not (min-height: 100dvh) {
.site {
min-height: 100vh;
}
}
| Topic | Guideline |
|---|---|
| Specificity | Keep between 0,1,0 and 0,2,1 |
| Nesting | Maximum 2 levels, 3 for exceptional cases |
| Component margins | None—use container gap |
| Margin direction | One direction only (prefer top) |
| IDs for styling | Avoid—use [id="name"] if needed |
!important | Exceptional cases only |
| Media queries | Last resort after intrinsic solutions |
After writing CSS:
0,1,0 to 0,2,1 rangedir="rtl" on containerStyles not applying:
Layout breaking at certain widths:
clamp() or Grid intrinsic sizingAccessibility issues:
Ask the user when:
Create and modify Gutenberg blocks following 10up engineering standards. Covers block.json metadata, dynamic rendering with PHP, attributes, deprecations, editor components, and the useBlockProps pattern. Use when creating new blocks, fixing block errors, or modifying existing block code.
Extend core WordPress blocks with custom attributes and controls using the 10up block extension pattern. Alternative to block styles when multiple controls are needed. Use when adding functionality to existing blocks rather than creating new ones.
Create reusable block patterns and synced patterns following 10up standards. Covers PHP file-based registration, pattern metadata, categories, and the block bindings API. Use when creating reusable layout components or content templates.
Build and modify WordPress block themes following 10up standards. Covers theme.json configuration, templates, template parts, patterns, style variations, and CSS organization. Use when working on block-based themes or Site Editor customizations.
Write clear, consistent commit messages following 10up conventions. Uses conventional commit style with lowercase formatting. Use when creating commits, writing PR descriptions, or generating changelogs.
Implement nested blocks and block composition using InnerBlocks. Covers parent/child relationships, templates, allowed blocks, and template locking. Use when building blocks that contain other blocks like cards, sections, or grid layouts.
