stylelint-plugin-grid 1.0.0

package/docs/rules/no-invalid-areas.md

@@ -0,0 +1,55 @@
+# no-invalid-areas
+
+Disallow malformed `grid-template-areas` declarations.
+
+This rule reports:
+
+- values without quoted row strings
+- row strings with different column counts
+- area tokens that are neither valid custom identifiers nor blank `.` markers
+
+## Incorrect
+
+```css
+.layout {
+  grid-template-areas:
+    "header header"
+    "nav";
+}
+```
+
+```css
+.layout {
+  grid-template-areas: "main 1bad";
+}
+```
+
+## Correct
+
+```css
+.layout {
+  grid-template-areas:
+    "header header"
+    "nav main";
+}
+```
+
+## Stylelint Config
+
+```js
+export default {
+  plugins: ["stylelint-plugin-grid"],
+  rules: {
+    "grid/no-invalid-areas": true
+  }
+};
+```
+
+## Related Rules
+
+- [`validate-area-shapes`](./validate-area-shapes.md) checks whether parsed named
+  areas form rectangles.
+- [`validate-track-counts`](./validate-track-counts.md) compares parsed template
+  dimensions with sibling track declarations.
+- [`grid-recommended`](./configs/grid-recommended.md) enables this rule by
+  default.

package/docs/rules/no-invalid-auto-repeat.md

@@ -0,0 +1,58 @@
+# no-invalid-auto-repeat
+
+Disallow definitely invalid CSS Grid auto-repeat track sizes.
+
+CSS Grid auto-repeat only accepts fixed track sizes. This rule catches common
+invalid patterns such as bare `fr` tracks and `minmax()` calls with intrinsic or
+flexible minimums inside `repeat(auto-fit, ...)` or `repeat(auto-fill, ...)`.
+
+The rule checks `grid-template-columns` and `grid-template-rows`. It avoids
+reporting runtime-dependent values such as `var()` and `env()`.
+
+## Incorrect
+
+```css
+.cards {
+  grid-template-columns: repeat(auto-fit, 1fr);
+}
+```
+
+```css
+.cards {
+  grid-template-columns: repeat(auto-fill, minmax(auto, 1fr));
+}
+```
+
+## Correct
+
+```css
+.cards {
+  grid-template-columns: repeat(auto-fit, minmax(12rem, 1fr));
+}
+```
+
+```css
+.cards {
+  grid-template-columns: repeat(auto-fill, [card] minmax(0, 1fr));
+}
+```
+
+## Stylelint Config
+
+```js
+export default {
+  plugins: ["stylelint-plugin-grid"],
+  rules: {
+    "grid/no-invalid-auto-repeat": true
+  }
+};
+```
+
+## Related Rules
+
+- [`no-invalid-minmax`](./no-invalid-minmax.md) checks invalid `minmax()`
+  minimums outside auto-repeat contexts too.
+- [`validate-track-counts`](./validate-track-counts.md) compares explicit track
+  counts with named area templates.
+- [`grid-recommended`](./configs/grid-recommended.md) enables this rule by
+  default.

package/docs/rules/no-invalid-minmax.md

@@ -0,0 +1,57 @@
+# no-invalid-minmax
+
+Disallow flexible `fr` values as the minimum argument in CSS Grid `minmax()`
+track sizes.
+
+In CSS Grid track sizing, the first `minmax()` argument must be an inflexible
+minimum. A value such as `minmax(1fr, 20rem)` is invalid and can cause the
+browser to ignore the declaration. Use an inflexible minimum such as `0`, a
+length, or a percentage instead.
+
+## Incorrect
+
+```css
+.layout {
+  grid-template-columns: minmax(1fr, 20rem) 2fr;
+}
+```
+
+```css
+.layout {
+  grid-auto-rows: minmax(0.5fr, auto);
+}
+```
+
+## Correct
+
+```css
+.layout {
+  grid-template-columns: minmax(0, 1fr) minmax(12rem, 20rem);
+}
+```
+
+```css
+.layout {
+  grid-auto-rows: minmax(10rem, auto);
+}
+```
+
+## Stylelint Config
+
+```js
+export default {
+  plugins: ["stylelint-plugin-grid"],
+  rules: {
+    "grid/no-invalid-minmax": true
+  }
+};
+```
+
+## Related Rules
+
+- [`no-invalid-auto-repeat`](./no-invalid-auto-repeat.md) checks auto-repeat
+  track sizes that must be fixed.
+- [`validate-track-counts`](./validate-track-counts.md) compares explicit track
+  counts with named area templates.
+- [`grid-recommended`](./configs/grid-recommended.md) enables this rule by
+  default.

package/docs/rules/no-mismatched-template-rows.md

@@ -0,0 +1,36 @@
+# no-mismatched-template-rows
+
+Require `grid-template-rows` track count to match `grid-template-areas` row
+count when both declarations appear in the same block.
+
+## Incorrect
+
+```css
+.layout {
+  grid-template-areas:
+    "header"
+    "main";
+  grid-template-rows: auto;
+}
+```
+
+## Correct
+
+```css
+.layout {
+  grid-template-areas:
+    "header"
+    "main";
+  grid-template-rows: auto 1fr;
+}
+```
+
+Dynamic track lists such as `repeat(auto-fit, ...)` are skipped because their
+count cannot be known statically.
+
+## Related Rules
+
+- [`validate-track-counts`](./validate-track-counts.md) also checks column-count
+  drift.
+- [`no-invalid-areas`](./no-invalid-areas.md) validates the parsed template rows.
+- [`grid-recommended`](./configs/grid-recommended.md) enables this rule by default.

package/docs/rules/no-overlapping-areas.md

@@ -0,0 +1,40 @@
+# no-overlapping-areas
+
+Disallow multiple selectors assigning the same single-name `grid-area` value in
+one stylesheet.
+
+This rule is not recommended by default because some projects intentionally
+stack multiple items in the same area. Use it when duplicate area assignments
+usually indicate layout collisions in your codebase.
+
+## Incorrect
+
+```css
+.header {
+  grid-area: header;
+}
+
+.mobileHeader {
+  grid-area: header;
+}
+```
+
+## Correct
+
+```css
+.header {
+  grid-area: header;
+}
+
+.sidebar {
+  grid-area: sidebar;
+}
+```
+
+## Related Rules
+
+- [`no-unused-areas`](./no-unused-areas.md) verifies that declared template areas
+  are actually assigned.
+- [`no-unknown-areas`](./no-unknown-areas.md) verifies that assigned area names
+  exist in a template.
+- [`grid-all`](./configs/grid-all.md) enables this stricter same-stylesheet rule.

package/docs/rules/no-unknown-areas.md

@@ -0,0 +1,39 @@
+# no-unknown-areas
+
+Disallow single-name `grid-area` references that do not match any named area
+declared by `grid-template-areas` in the same stylesheet.
+
+## Incorrect
+
+```css
+.layout {
+  grid-template-areas: "header main";
+}
+
+.sidebar {
+  grid-area: sidebr;
+}
+```
+
+## Correct
+
+```css
+.layout {
+  grid-template-areas: "header main";
+}
+
+.header {
+  grid-area: header;
+}
+```
+
+The rule only checks single-name `grid-area` declarations. Line-based shorthand
+placements are ignored.
+
+## Related Rules
+
+- [`no-unused-areas`](./no-unused-areas.md) checks the inverse problem: declared
+  template areas without matching item assignments.
+- [`no-overlapping-areas`](./no-overlapping-areas.md) reports duplicate
+  single-name assignments in the same stylesheet.
+- [Current status](./guides/current-status.md) explains the same-file assumptions.

package/docs/rules/no-unused-areas.md

@@ -0,0 +1,44 @@
+# no-unused-areas
+
+Disallow named template areas that are never referenced by a single-name
+`grid-area` declaration in the same stylesheet.
+
+This rule is intentionally not recommended by default. It is useful when grid
+containers and grid items are authored together, but it can be noisy when
+templates and items live in separate files.
+
+## Incorrect
+
+```css
+.layout {
+  grid-template-areas: "header main";
+}
+
+.main {
+  grid-area: main;
+}
+```
+
+## Related Rules
+
+- [`no-unknown-areas`](./no-unknown-areas.md) catches item assignments that do not
+  exist in any same-stylesheet template.
+- [`no-overlapping-areas`](./no-overlapping-areas.md) catches duplicate
+  single-name assignments.
+- [`grid-all`](./configs/grid-all.md) enables this stricter same-stylesheet rule.
+
+## Correct
+
+```css
+.layout {
+  grid-template-areas: "header main";
+}
+
+.header {
+  grid-area: header;
+}
+
+.main {
+  grid-area: main;
+}
+```

package/docs/rules/overview.md

@@ -0,0 +1,54 @@
+---
+title: Overview
+description: Overview of stylelint-plugin-grid and its package surface.
+---
+
+# stylelint-plugin-grid
+
+`stylelint-plugin-grid` validates authored CSS Grid templates, area
+assignments, and grid-specific compatibility patterns that generic declaration
+rules do not understand.
+
+The package intentionally focuses on static CSS that Stylelint can inspect
+reliably: `grid-template-areas`, sibling template track declarations, and
+single-name `grid-area` assignments.
+
+## Exports
+
+- A default Stylelint plugin pack export.
+- A plugin-scoped shareable config map: `gridPluginConfigs`
+  - `grid-recommended`
+  - `grid-all`
+- Static metadata exports: `meta`, `rules`, `ruleNames`, `ruleIds`, and
+  `configNames`.
+
+## Rule Families
+
+The initial catalog covers:
+
+- malformed `grid-template-areas` row strings and area tokens
+- non-rectangular named areas
+- invalid auto-repeat and `minmax()` track sizing syntax
+- row and column track-count drift
+- unknown or unused named area references
+- duplicate single-name area assignments that can create overlapping grid items
+- consistent grid area naming
+- dense auto-placement patterns that can disconnect visual and source order
+- column auto-placement blocks that omit explicit row sizing
+- migration from legacy `grid-gap` aliases to modern gap properties
+
+The package does not try to infer runtime layout across separate files,
+framework conditionals, or class composition. Rules that need same-stylesheet
+knowledge are kept out of `grid-recommended` unless their false-positive risk is
+low.
+
+## Next Steps
+
+- [Install and configure the plugin](./getting-started.md).
+- [Compare the shareable configs](./configs/).
+- [Review the current static-analysis boundaries](./guides/current-status.md).
+- Start with [`no-invalid-areas`](./no-invalid-areas.md),
+  [`no-invalid-auto-repeat`](./no-invalid-auto-repeat.md),
+  [`no-invalid-minmax`](./no-invalid-minmax.md),
+  [`validate-area-shapes`](./validate-area-shapes.md), and
+  [`validate-track-counts`](./validate-track-counts.md) for template correctness.

package/docs/rules/prefer-gap-properties.md

@@ -0,0 +1,45 @@
+# prefer-gap-properties
+
+Prefer modern `gap`, `row-gap`, and `column-gap` over legacy grid gap aliases.
+
+This rule is autofixable.
+
+## Incorrect
+
+```css
+.layout {
+  display: grid;
+  grid-gap: 1rem;
+  grid-column-gap: 2rem;
+}
+```
+
+## Correct
+
+```css
+.layout {
+  display: grid;
+  gap: 1rem;
+  column-gap: 2rem;
+}
+```
+
+## Stylelint Config
+
+```js
+export default {
+  plugins: ["stylelint-plugin-grid"],
+  rules: {
+    "grid/prefer-gap-properties": true
+  }
+};
+```
+
+## Related Docs
+
+- [Getting Started](./getting-started.md) shows how to enable the recommended
+  baseline.
+- [`grid-recommended`](./configs/grid-recommended.md) enables this autofixable rule
+  by default.
+- [`validate-track-counts`](./validate-track-counts.md) covers template dimensions
+  after gap declarations are modernized.

package/docs/rules/require-explicit-rows-with-column-flow.md

@@ -0,0 +1,56 @@
+# require-explicit-rows-with-column-flow
+
+Require explicit row sizing when a rule uses `grid-auto-flow: column`.
+
+Column auto-placement fills columns instead of rows. Without row sizing in the
+same block, browsers can create implicit tracks in surprising ways and produce a
+single long row-like layout. This rule asks for either `grid-template-rows` or
+`grid-auto-rows` next to the `grid-auto-flow: column` declaration.
+
+This is intentionally an opt-in policy rule. It checks same-block declarations
+only and does not try to infer row sizing from other selectors or media-query
+cascade layers.
+
+## Incorrect
+
+```css
+.cards {
+  grid-auto-flow: column;
+  grid-template-columns: repeat(3, 1fr);
+}
+```
+
+## Correct
+
+```css
+.cards {
+  grid-auto-flow: column;
+  grid-auto-rows: minmax(10rem, auto);
+}
+```
+
+```css
+.cards {
+  grid-auto-flow: column;
+  grid-template-rows: repeat(3, minmax(0, 1fr));
+}
+```
+
+## Stylelint Config
+
+```js
+export default {
+  plugins: ["stylelint-plugin-grid"],
+  rules: {
+    "grid/require-explicit-rows-with-column-flow": true
+  }
+};
+```
+
+## Related Rules
+
+- [`no-dense-auto-flow`](./no-dense-auto-flow.md) catches dense packing mode
+  when source order safety matters.
+- [`validate-track-counts`](./validate-track-counts.md) compares explicit track
+  counts with named area templates.
+- [`grid-all`](./configs/grid-all.md) enables this stricter policy rule.

package/docs/rules/validate-area-shapes.md

@@ -0,0 +1,46 @@
+# validate-area-shapes
+
+Require every named grid template area to form one contiguous rectangle.
+
+CSS Grid rejects non-rectangular areas. This rule catches the problem at the
+authored template declaration instead of leaving it to browser behavior.
+
+## Incorrect
+
+```css
+.layout {
+  grid-template-areas:
+    "main side"
+    "main main";
+}
+```
+
+## Correct
+
+```css
+.layout {
+  grid-template-areas:
+    "main side"
+    "main side";
+}
+```
+
+## Stylelint Config
+
+```js
+export default {
+  plugins: ["stylelint-plugin-grid"],
+  rules: {
+    "grid/validate-area-shapes": true
+  }
+};
+```
+
+## Related Rules
+
+- [`no-invalid-areas`](./no-invalid-areas.md) catches malformed template strings
+  before shape validation matters.
+- [`validate-track-counts`](./validate-track-counts.md) checks the track dimensions
+  for the same template.
+- [`no-mismatched-template-rows`](./no-mismatched-template-rows.md) focuses only on
+  row-count drift.

package/docs/rules/validate-track-counts.md

@@ -0,0 +1,39 @@
+# validate-track-counts
+
+Require sibling `grid-template-rows` and `grid-template-columns` declarations to
+match the dimensions of `grid-template-areas`.
+
+## Incorrect
+
+```css
+.layout {
+  grid-template-areas:
+    "nav main"
+    "nav footer";
+  grid-template-columns: 12rem;
+  grid-template-rows: auto auto auto;
+}
+```
+
+## Correct
+
+```css
+.layout {
+  grid-template-areas:
+    "nav main"
+    "nav footer";
+  grid-template-columns: 12rem 1fr;
+  grid-template-rows: auto auto;
+}
+```
+
+The rule understands explicit tracks and integer `repeat(...)` notation. It
+skips dynamic repeat counts.
+
+## Related Rules
+
+- [`no-invalid-areas`](./no-invalid-areas.md) validates the template rows this rule
+  measures.
+- [`no-mismatched-template-rows`](./no-mismatched-template-rows.md) is the narrower
+  row-only check.
+- [`grid-recommended`](./configs/grid-recommended.md) enables this rule by default.