feat(Stack): add tight/cozy spacing values and directional padding props

[hectahertz]

Closes github/primer#6466

Adds two new spacing values (tight at 4px, cozy at 12px) to the gap and padding scales, filling holes in the spacing ramp that were pushing devs toward utility classes or CSS modules. Also adds paddingBlock and paddingInline props for per-axis padding control, and switches the CSS internals from padding shorthand to padding-block + padding-inline longhands so external overrides don't get clobbered.

New spacing scale:

Name	Pixels
none	0
tight	4
condensed	8
cozy	12
normal	16
spacious	24

Directional padding: paddingBlock and paddingInline accept the same scale as padding and override their respective axis. padding="normal" paddingInline="spacious" sets block padding to 16px and inline padding to 24px.

Changelog

New

• gap and padding props now accept 'tight' (4px) and 'cozy' (12px) values
• paddingBlock prop for block-axis (vertical) padding control
• paddingInline prop for inline-axis (horizontal) padding control

Changed

• padding prop CSS internals switched from padding shorthand to padding-block + padding-inline longhands for predictable override behavior

Removed

N/A

Rollout strategy

• Minor release

Testing & Reviewing

1. Check the new Storybook stories: Components/Stack/Features/GapScale, PaddingScale, and DirectionalPadding
2. Verify existing padding prop behavior is unchanged (backward compatible, same visual output)
3. Verify paddingBlock/paddingInline override the corresponding axis of padding when both are set

Merge checklist

• Added/updated tests
• Added/updated documentation
• Added/updated previews (Storybook)
• Changes are SSR compatible
• Tested in Chrome
• Tested in Firefox
• Tested in Safari
• Tested in Edge
• (GitHub staff only) Integration tests pass at github/github-ui (Learn more about how to run integration tests)

[changeset-bot]

🦋 Changeset detected

Latest commit: 5d77814

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@primer/react	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

⚠️ Action required

👋 Hi, this pull request contains changes to the source code that github/github-ui depends on. If you are GitHub staff, test these changes with github/github-ui using the integration workflow. Check the integration testing docs for step-by-step instructions. Or, apply the integration-tests: skipped manually label to skip these checks.

[Copilot]

Pull request overview

Adds additional spacing options and directional padding controls to Stack, expanding the ergonomics of layout spacing without requiring utility classes/custom CSS.

Changes:

• Extend Stack gap/padding scales with new values: tight (4px) and cozy (12px).
• Add paddingBlock and paddingInline props (including responsive support) and emit corresponding data attributes.
• Switch internal padding styling from padding shorthand to padding-block/padding-inline longhands, plus add new CSS selectors and Storybook feature stories.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/react/src/Stack/Stack.tsx	Extends spacing union types; adds paddingBlock/paddingInline props and data attributes.
packages/react/src/Stack/Stack.module.css	Adds tight/cozy spacing rules; introduces block/inline padding rules and responsive variants; moves to logical longhands.
packages/react/src/Stack/tests/Stack.test.tsx	Expands coverage for new scale values and new directional padding props (attribute assertions).
packages/react/src/Stack/Stack.features.stories.tsx	Adds feature stories for visual verification of new spacing scales and directional padding behavior.
packages/react/src/Stack/Stack.docs.json	Updates prop type strings and documents new props.
.changeset/stack-spacing-options.md	Adds changeset for a minor release of @primer/react.

[Copilot]

JSX uses single-quoted attribute values for label here (e.g. label='padding="normal" …'), which is inconsistent with the repo’s Prettier/JSX formatting and will likely be rewritten by npx prettier --write. Please reformat these to the standard JSX attribute style (e.g. use double quotes with escaping or a {...} string literal) and run Prettier on the file.

[hectahertz]

cc @HiroAgustin @dfosco, this addresses your requests for more Stack spacing options and consistent padding overrides from the thread. Would love your feedback!

[liuliu-dev]

code looks good! ✨

[dfosco]

@hectahertz From what you described here this looks great and addresses all of my points from the thread! 🙌

[HiroAgustin]

This is great! Funnily enough: https://github.com/github/github-ui/pull/16820/changes#r2988457348

On top of this it would be nice to expand the hx_utilities gap classes to fill in the missing gaps:

.gap-1pt5 {
  gap: var(--base-size-6) !important;
}

.gap-2pt5 {
  gap: var(--base-size-12) !important;
}

.gap-3pt5 {
  gap: var(--base-size-20) !important;
}