feat(box): DLT-3523 add positioning props to DtBox

[Francis Rupert (francisrupert)]

🛠️ Type Of Change

These types will increment the version number on release:

• Feature

📖 Jira Ticket

https://dialpad.atlassian.net/browse/DLT-3523

📖 Description

Adds DtBox props for container positioning:

• position
• logical inset props
• zIndex

Includes token-backed styling, prop validation, tests, stories, Combinator support, docs, and AI guidance.

💡 Context

DtBox is the primitive for token-backed containers.

This lets common positioned containers use DtBox props instead of CSS utility classes.

Does not remove utility escape hatches. Utilities still apply for non-DtBox elements, responsive positioning, calc/arbitrary/reset values, and advanced overlay cases.

📝 Checklist

For all PRs:

• I have ensured no private Dialpad links or info are in the code or pull request description (Dialtone is a public repo!).
• I have reviewed my changes.
• I have added all relevant documentation.
• I have considered the performance impact of my change.

For all Vue changes:

• I have added / updated unit tests.
• I have validated components with a screen reader.
• I have validated components keyboard navigation.

For all CSS changes:

• I have used design tokens whenever possible.
• I have considered how this change will behave on different screen sizes.
• I have visually validated my change in light and dark mode.
• I have used gap or flexbox properties for layout instead of margin whenever possible.

asdf.mp4

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Central YAML (inherited), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: 66972e70-c50b-4407-a11b-9a4e59d2798e

📥 Commits

Reviewing files that changed from the base of the PR and between 44eb364 and 880b876.

📒 Files selected for processing (3)

• apps/dialtone-documentation/docs/utilities/layout/coordinates.md
• packages/dialtone-css/lib/build/less/components/box.less
• packages/dialtone-vue/components/Box/Box.test.js

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• dialpad/ios (manual)
• dialpad/firespotter (manual)
• dialpad/semantic-release-changelog-json (auto-detected)
• dialpad/conventional-changelog-angular (auto-detected)

---

Added token-backed positioning props to DtBox: position, logical inset*, and zIndex, with validators and modifier-class generation (CSS/LESS token registrations). Updated Combinator exclusions and tokens, plus Storybook stories, unit tests, and docs/guidance. Removed GitHub Packages npm auth step in CI.

Overall Judgement: ✅ Ready to merge — the change is well-tested and documented with guidance updates, and the CI environment adjustment addresses the reported lockfile/package resolution issue.

Walkthrough

This PR adds DtBox positioning support across token resolution, CSS generation, Vue props, stories, tests, and documentation. It also removes the GitHub Packages npm authentication step from the environment setup action.

Changes

DtBox Positioning Feature

Layer / File(s)	Summary
Token and variant contracts packages/combinator/src/lib/tokens.js, packages/combinator/src/variants/variants_box.js, packages/combinator/src/lib/exclusion_rules.js, packages/combinator/src/components/option_bar/option_bar_member_group.vue, packages/combinator/src/lib/*test.js	Adds coordinate and z-index token resolution, inset/position token lists, Box default prop metadata, conditional inset exclusions, prop ordering, and tests for the new resolution and exclusion behavior.
Box CSS generation packages/dialtone-css/lib/build/less/components/box.less	Adds Box custom properties, reworks spacing and inset mixins, adjusts base cascade placement, and generates positioning and z-index modifier classes.
DtBox Vue API and stories packages/dialtone-vue/components/Box/*	Expands Box constants, validators, props, class generation, Storybook controls, and unit tests to cover position, inset, and z-index props.
Documentation and guidance updates .agents/resources/*, .claude/rules/*, .claude/skills/utility.md, apps/dialtone-documentation/docs/..., packages/dialtone-docs/src/content/..., packages/dialtone-mcp-server/client-rules.json	Updates agent rules, Claude skill docs, product docs, reference pages, utility docs, announcement content, and MCP client rules to describe the new primitive-first and logical-positioning guidance.

GitHub Actions environment setup

Layer / File(s)	Summary
Setup action auth step removal .github/actions/setup-environment/action.yml	Removes the npm authentication step from the composite setup action before dependency installation.

Possibly related PRs

• dialpad/dialtone#1344: Updates the same parity documentation area around agent tooling and Claude rule files.

Suggested reviewers: braddialpad, ninarepetto, belumontoya

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch box-positioning-properties

---

_{Comment @coderabbitai help to get the list of available commands.}

[Brad Paugh (braddialpad)]

Looking into lockfile issue

[coderabbitai]

Actionable comments posted: 3

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/dialtone-css/lib/build/less/components/box.less (1)

176-194: 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Comments no longer match the reordered declarations.

The "Width cascade: specific → axis → shorthand → 0" comment (line 178) now sits directly above only border-radius, while the actual border-width cascade it describes has moved several lines down, past the new inset declarations. Similarly, // Shadow (line 181) now precedes box-shadow and the unrelated inset-block/inset-inline assignments. Functionally harmless (different properties, order-independent), but misleading for future maintainers.

✏️ Suggested comment fix

   border-style: solid;
   border-radius: var(--box-br);

   // Shadow
   box-shadow: var(--box-shadow, none);
+
+  // Inset
   inset-block: var(--box-ibs, var(--box-inset-block, var(--box-inset, auto))) var(--box-ibe, var(--box-inset-block, var(--box-inset, auto)));
   inset-inline: var(--box-iis, var(--box-inset-inline, var(--box-inset, auto))) var(--box-iie, var(--box-inset-inline, var(--box-inset, auto)));
+
+  // Border width cascade: specific → axis → shorthand → 0
   border-block-start-width:  var(--box-bwbs, var(--box-bwbl, var(--box-bw, 0)));

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/dialtone-css/lib/build/less/components/box.less` around lines 176 -
194, The comments in the box rules are now attached to the wrong declarations,
especially around the border-width cascade and the shadow section in the box
mixin. Update the comment placement in the `box.less` block so the “Width
cascade: specific → axis → shorthand → 0” note sits directly above the
`border-block-start-width`/`border-inline-*` rules, and move `// Shadow` to
cover only `box-shadow` in the `box` styling section. Keep the rest of the
declaration order unchanged while aligning comments with the related properties.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/dialtone-documentation/docs/utilities/layout/coordinates.md`:
- Around line 14-16: Clarify the scope in the coordinates documentation: the
`d-t-*`, `d-r-*`, `d-b-*`, `d-l-*`, `d-x-*`, `d-y-*`, `d-all-*`, and logical
aliases like `d-ibs-*` only define offsets and do not by themselves position
elements. Update the wording near the coordinate utility description in
`coordinates.md` to avoid saying they “absolutely position” elements, and
instead explain that they are used with positioning utilities such as
`d-ps-relative` and `d-ps-absolute` when needed.

In `@packages/dialtone-vue/components/Box/Box.test.js`:
- Around line 419-448: The console.warn spy setup is duplicated across the Box
test cases in the DT_BOX_INSET_VALUES, DT_BOX_INSET_SIDE_VALUES, and invalid
prop validation blocks. Move the repeated vi.spyOn(console,
'warn').mockImplementation(() => {}) into a shared beforeEach in the Box test
suite, and keep only the per-test mountComponent and assertion logic inside each
it/it.each case. This will align with the existing test conventions and reduce
repetition while preserving the current warning expectations.
- Around line 456-466: The Box test groups three class assertions in one case,
but the test suite requires one assertion per test. Split the current `applies
multiple positioning classes simultaneously` case in `Box.test.js` into separate
`it` blocks or an `it.each` table for the `mountComponent` prop/class pairs,
using the existing `wrapper.classes()` expectations for `position`,
`insetBlockStart`, and `zIndex` individually.

---

Outside diff comments:
In `@packages/dialtone-css/lib/build/less/components/box.less`:
- Around line 176-194: The comments in the box rules are now attached to the
wrong declarations, especially around the border-width cascade and the shadow
section in the box mixin. Update the comment placement in the `box.less` block
so the “Width cascade: specific → axis → shorthand → 0” note sits directly above
the `border-block-start-width`/`border-inline-*` rules, and move `// Shadow` to
cover only `box-shadow` in the `box` styling section. Keep the rest of the
declaration order unchanged while aligning comments with the related properties.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Central YAML (inherited), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: e92c0db5-a685-4027-a54b-cb84f9e28ee1

📥 Commits

Reviewing files that changed from the base of the PR and between 42825ec and ee37202.

📒 Files selected for processing (30)

• .agents/resources/agent-tooling-parity.md
• .agents/resources/rule-map.md
• .agents/resources/rules/css-utilities.md
• .agents/resources/rules/logical-naming.md
• .claude/rules/css-utilities.md
• .claude/rules/logical-naming.md
• .claude/skills/utility.md
• apps/dialtone-documentation/docs/components/box.md
• apps/dialtone-documentation/docs/dialtone/whats-new/posts/2026-4-22.md
• apps/dialtone-documentation/docs/foundations/size-and-space/index.md
• apps/dialtone-documentation/docs/scratch.md
• apps/dialtone-documentation/docs/utilities/layout/coordinates.md
• apps/dialtone-documentation/docs/utilities/layout/position.md
• apps/dialtone-documentation/docs/utilities/layout/z-index.md
• packages/combinator/src/components/option_bar/option_bar_member_group.vue
• packages/combinator/src/lib/exclusion_rules.js
• packages/combinator/src/lib/exclusion_rules.test.js
• packages/combinator/src/lib/tokens.js
• packages/combinator/src/lib/tokens.test.js
• packages/combinator/src/variants/variants_box.js
• packages/dialtone-css/lib/build/less/components/box.less
• packages/dialtone-docs/src/content/development/development-css-utilities.md
• packages/dialtone-docs/src/content/reference/reference-component-api-patterns.md
• packages/dialtone-mcp-server/client-rules.json
• packages/dialtone-vue/components/Box/Box.stories.js
• packages/dialtone-vue/components/Box/Box.test.js
• packages/dialtone-vue/components/Box/Box.vue
• packages/dialtone-vue/components/Box/BoxConstants.js
• packages/dialtone-vue/components/Box/Validators.js
• packages/dialtone-vue/components/Box/index.js

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• dialpad/ios (manual)
• dialpad/firespotter (manual)
• dialpad/semantic-release-changelog-json (auto-detected)
• dialpad/conventional-changelog-angular (auto-detected)

[Brad Paugh (braddialpad)]

lockfile / ci issues fixed. Francis Rupert (@francisrupert) can you do "corepack enable" in dialtone directory to make sure it always uses the correct repository version of pnpm. (this is a very recent new feature)

[github-actions]

✔️ Deploy previews ready!
😎 Dialtone documentation preview: https://dialtone.dialpad.com/deploy-previews/pr-1355/
😎 Dialtone-vue preview: https://dialtone.dialpad.com/vue/deploy-previews/pr-1355/