Skip to content

Commit d8d8e87

Browse files
committed
Correct specificity figure and rewrite README styling conventions for accuracy
Re-review of the final-review fixes found two text-only errors: - .nav-links a's specificity was given as (0,4,1); the compiled selector (.nav-links[data-astro-cid-*] a[data-astro-cid-*]) is actually (0,3,1). The conclusion is unchanged (it still outranks .nav-github's (0,2,0)), only the arithmetic in the comment and deferred-findings.md was wrong. - The README's styling-conventions bullets described a consistency the code doesn't have: utilities aren't reserved for "simple" outer-element rules (7 of 9 components use scoped CSS even for 1-3 declaration rules), and "never set the same property both ways" is contradicted by Hero's deliberate utility-base-plus-scoped-media-override pattern. Rewrote the section to state plainly that the split is by component, not by rule complexity, that the codebase isn't uniform, and to recommend the majority (scoped-CSS) pattern for new sections. 11/11 parity tests pass, astro build clean, astro check clean.
1 parent 5d2190a commit d8d8e87

2 files changed

Lines changed: 15 additions & 7 deletions

File tree

README.md

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -11,16 +11,24 @@ npm run dev
1111

1212
## Styling conventions
1313

14-
- Use Tailwind utilities for simple layout and spacing on a component's outer
15-
elements.
16-
- Write a scoped `<style>` rule for anything with more than about four
17-
declarations, or that deserves a name worth reading.
14+
- Two approaches exist today, split by component rather than by rule
15+
complexity: `Navbar.astro` and `Hero.astro` put Tailwind utilities on
16+
their outer markup; the other seven components (`Stats`, `FeaturedCard`,
17+
`CategoryCard`, `LibCard`, `Footer`, `Install`, `ScrollTop`) and the page
18+
section shells in `index.astro` are scoped-CSS-only, even for
19+
one-declaration rules. The codebase is not uniform.
20+
- For new sections, follow the majority pattern: a scoped `<style>` rule per
21+
component, named for what it styles. Reserve utilities for one-off
22+
arbitrary values on an element that doesn't need a named rule.
1823
- Rules shared across multiple files go in `src/styles/global.css`, under
1924
`@layer components`.
2025
- Never set the same property both ways on the same element. Astro's scoped
2126
styles are unlayered, so they beat both `@layer base` and Tailwind
22-
utilities — a utility and a scoped rule targeting the same property do not
23-
resolve by specificity the way you'd expect; pick one per property.
27+
utilities — a utility and a scoped rule targeting the same property
28+
resolve by rule type, not by specificity the way you'd expect.
29+
`Hero.astro`'s utility padding (`pt-40 pb-24`) overridden by a scoped
30+
`@media` rule for mobile is the one deliberate use of that pattern here;
31+
keep it commented if you add another.
2432

2533
## Test
2634

src/components/Navbar.astro

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@ import { Icon } from 'astro-icon/components';
7575
}
7676

7777
/* .nav-github, baseline.html:172-182. !important is required here:
78-
.nav-links a (0,4,1) outranks .nav-github (0,2,0), both unlayered, so
78+
.nav-links a (0,3,1) outranks .nav-github (0,2,0), both unlayered, so
7979
specificity — not layering — decides. Verified: removing it renders
8080
#94a3b8 (--color-text-secondary) instead of #e2e8f0
8181
(--color-text-primary). Do not drop it. */

0 commit comments

Comments
 (0)