Imported from skdud3229/skdud3229.github.io (AGENTS.md). Install upstream with npx skills add skdud3229/skdud3229.github.io. Copyright stays with the author.

Frontend Refactoring Rules

These rules govern all frontend styling and template refactoring in this repository.

Abstraction threshold

Do not create a shared abstraction merely because two pieces of UI currently look similar.

Create a shared abstraction only when one of these conditions is true:

• The same pattern occurs at least three times.
• The pattern is an intentional design-system concept.

Prefer the smallest appropriate level of abstraction:

design token -> primitive -> component -> one-off CSS

Avoid premature component variants. A variant must represent a stable, intentional difference in behavior or visual semantics, not a temporary implementation detail.

Design-system foundations

Use and extend these explicit scales instead of introducing arbitrary values.

Spacing

4 / 8 / 12 / 16 / 24 / 32 / 48 / 64

Typography

text-xs / text-sm / text-md / text-lg / heading-sm / heading-md / heading-lg

Layout primitives

• Stack: vertical flow with controlled gaps.
• Inline: horizontal alignment of a small number of items.
• Container: page-width constraint and horizontal gutters.
• Grid: structured columns or repeated content.
• Cluster: wrapping inline items with consistent gaps.

Breakpoints

• mobile
• tablet
• desktop

For this site, mobile is <= 767px, tablet is 768px–1100px, and desktop starts at 1101px. The tablet boundary exists because the combined main, sidebar, and column-gap minimums no longer fit without compression.

Use these named concepts consistently. Do not add one-off breakpoints without a documented layout requirement.

Tokens

Raw visual values must have a semantic token before broad reuse:

• --color-*
• --space-*
• --radius-*
• --shadow-*
• --z-*

Typography and layout values should likewise use named tokens when they are part of the design system. One-off CSS may use a local value only when it does not represent a reusable visual decision.

Ownership rules

• Page: composition only. It selects components/primitives and passes data; it does not style child component internals.
• Component: owns its visual styling, states, and component-specific behavior.
• Primitive: owns reusable layout or low-level style behavior independent of page content.
• Token: is the single source of raw visual values.

Keep selectors shallow and component-scoped. Avoid page-level selectors that style component internals, deeply nested selectors, global behavior overrides, generic common.css, and giant utility files.

Page layout contract

All primary views share one page frame:

• A centered content container, a fixed main reading column, and a sidebar column form the desktop grid.
• Search and post-detail headers reserve the same compact header-region height. Home uses a deliberately taller introductory hero region, expressed as a card.
• The sidebar starts at the header-region start on desktop and becomes a normal document-flow section on mobile.
• Persistent controls, such as the home button, live in a separate outer rail. They must not occupy the content container or overlap a page heading.

Refactoring process

1. Inspect usage before changing or removing a rule.
2. Preserve existing behavior unless a change is explicitly requested.
3. Introduce tokens and primitives only when they meet the abstraction threshold.
4. Migrate one component or layout concern at a time.
5. Verify desktop, tablet, and mobile layouts after each structural change.
6. Remove legacy CSS only after all active references have migrated.