---
name: css-flexbox-layout-documenter
description: "Writes the documentation a teammate needs to change a Flexbox layout safely: what it is for, what each container and item property does, how it responds at each breakpoint, and a minimal HTML example. Use when an existing Flexbox layout needs written documentation covering its purpose, container and item settings, breakpoints, and what is safe to change. Do not use for fixing a broken layout, generating new CSS, or writing a general Flexbox tutorial. Related topics: coding, css."
---

# CSS Flexbox Layout Documenter

Writes the documentation a teammate needs to change a Flexbox layout safely: what it is for, what each container and item property does, how it responds at each breakpoint, and a minimal HTML example.

## When to use

Use this skill when an existing Flexbox layout needs written documentation covering its purpose, container and item settings, breakpoints, and what is safe to change. Do not use it for fixing a broken layout, generating new CSS, or writing a general Flexbox tutorial.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. State the layout's purpose and the invariant that must hold, in two sentences a new teammate can repeat.
3. Tabulate container properties with value and reason, then item properties, flagging every exception to the pattern and why it exists.
4. Describe each breakpoint by what the user sees change, with the declarations that cause it.
5. Write the Safe to change and Will break the layout lists from the properties documented above.
6. Produce a minimal HTML snippet and a CSS block that reproduce the layout in a sandbox.

## Inputs

- **Flex container selector** (free text, e.g. ".site-nav")
- **Flex item selectors** (longer free text)
- **Main axis direction** (choose one: row, row-reverse, column, column-reverse)
- **Wrap behaviour** (choose one: nowrap, wrap, wrap-reverse)
- **Properties that matter in this layout** (choose any: justify-content, align-items, align-content, gap, order, flex-grow, flex-shrink, flex-basis)
- **Layout use case** (free text, e.g. "navigation bar or card grid or form row")
- **Responsive breakpoints** (longer free text)

## Output

A Markdown document with sections Overview, Container Settings (table), Item Settings (table), Responsive Adjustments, Safe to Change, Will Break the Layout, and Example with fenced HTML and CSS blocks.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### CSS Flexbox Layout Documenter

Document this Flexbox layout so another developer can modify it without breaking it.

- Flex container selector: {{Flex container selector}}
- Flex item selectors: {{Flex item selectors}}
- Main axis direction: {{Main axis direction}}
- Wrap behaviour: {{Wrap behaviour}}
- Properties that matter in this layout: {{Properties that matter in this layout}}
- Layout use case: {{Layout use case}}
- Responsive breakpoints: {{Responsive breakpoints}}

Open with the purpose of the layout in two sentences and the one thing that must not change (for example, the logo stays left and the actions stay right). Describe the container settings as a table with property, value, and the reason it is set, written for a reader who knows CSS but not this codebase. Do the same for the items, calling out any that break the pattern (an nth-child exception, an order override) and why. For each breakpoint, state what changes and what the user sees, not just the declarations. Add a short "Safe to change" list and a "Will break the layout" list, since those two lists are what the next developer reads first. Close with a minimal HTML snippet that demonstrates the layout with placeholder content, and a fenced CSS block with the documented rules, both small enough to paste into a sandbox.

## Pitfalls

- Restating declarations without the reason, which tells the next developer nothing about whether they can change them.
- Skipping the nth-child or order exceptions; those are exactly the rules that surprise someone editing the layout later.
- Documenting breakpoints as code only, when the useful fact is what the user sees change at that width.
