Skip to content

chore(components): add development documentation#4493

Open
thomasguillot wants to merge 1 commit intotrunkfrom
add/components-development-doc
Open

chore(components): add development documentation#4493
thomasguillot wants to merge 1 commit intotrunkfrom
add/components-development-doc

Conversation

@thomasguillot
Copy link
Contributor

@thomasguillot thomasguillot commented Feb 16, 2026

All Submissions:

Changes proposed in this Pull Request:

Related: #4486 and #4487


If some of the documentation is incorrect, feel free to update


Adds a comprehensive DEVELOPMENT.md for the components package to guide internal developers and AI tools. This is probably not perfect but I think this is a starting point.

What's in the guide

  • Purpose & when to use – When to use Newspack components vs @wordpress/components (backend wizards, blocks, frontend) and an "in short" summary.
  • Component selection hierarchy – Step-by-step: Newspack first → WordPress → designer review for new components.
  • Design & layout at a glance – Spacing scale (8px unit), when to use HStack/VStack/Grid, hierarchy (SectionHeader → Card → ActionCard), breakpoints, and pointer to full Styling section.
  • Available components – Categorized list (layout, form, content, wizard, etc.) with design/usage notes where relevant.
  • Usage – By context (backend, blocks, frontend) and common patterns (Wizard, withWizardScreen, withWizard, hooks, AutocompleteTokenField in blocks) with code examples.
  • Import patterns – Monorepo (relative paths) vs npm (newspack-components), alphabetical named imports, no namespace import, Router proxy.
  • Common WordPress components – Reference list (form, layout, panels, etc.), icons (WordPress/icons then newspack-icons, no Dashicons), experimental APIs with eslint-disable-line.
  • Styling – Naming (BEM-ish), spacing scale table, layout guidance, responsive breakpoints, visual hierarchy patterns, component states.
  • Contributing – Component patterns (wrapping vs standalone) and development guidelines.

Benefits

  • Single source of truth for how and when to use components in wizards/settings.
  • Design system in one place – Spacing, hierarchy, breakpoints, and states documented.
  • AI-friendly – Clear, consistent instructions for both humans and AI (selection, imports, patterns).

How to test the changes in this Pull Request:

👍

Other information:

  • Have you added an explanation of what your changes do and why you'd like us to include them?
  • Have you written new tests for your changes, as applicable?
  • Have you successfully ran tests with your changes locally?

@thomasguillot thomasguillot requested a review from a team as a code owner February 16, 2026 17:41
@thomasguillot thomasguillot added the [Status] Needs Review The issue or pull request needs to be reviewed label Feb 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Status] Needs Review The issue or pull request needs to be reviewed

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant