docs(DX-2): PROFILES.md — writing an emit profile - #23
Merged
Conversation
Profiles are pure data authored in the consumer's codebase against the published package — the studio's external astryx-profile.ts is the reference for exactly that pattern; the in-repo shadcnProfile (with goldens and the parity suite) is only for ecosystem-canonical contracts. Documents the Profile anatomy, the three judgment calls (synthesis, casualties, compound flattening), the never-silent-loss stance, and validation via transform/emitSurface. README links the guide. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Adds an “emit profile” authoring guide to dspack-emit and links it from the README so external consumers can write their own profiles against the published package API (per DX-2 / RFC companion doc goal).
Changes:
- Adds
docs/PROFILES.mdexplaining what an emit profile is, where it should live, its shape, and how to validate it viatransform/emitSurface. - Updates
README.mdto link to the new guide and the broader adoption path.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| README.md | Adds a pointer to the new profile authoring guide and adoption guide. |
| docs/PROFILES.md | New documentation detailing profile structure, judgment points, and validation workflow. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+44
to
+53
| | Field | What it is | Mode | | ||
| |---|---|---| | ||
| | `catalogTitle`, `catalogDescription`, `catalogIdBase`, `instructions` | Catalog identity; the versioned `$id` is built from `catalogIdBase` | mechanical | | ||
| | `primaryColorToken` | Which contract token (`category` + `name`) supplies `theme.primaryColor` | judgment (small) | | ||
| | `components: ComponentPlan[]` | One plan per mapped dspack component | mostly mechanical, see below | | ||
| | `synthesized: ComponentPlan[]` | Target primitives your contract does **not** contain (Text, Column, …). dspack describes a component library, not a layout system; renderable surfaces need structure, so you synthesize it — and it is recorded as a fidelity finding, never smuggled in | **judgment** | | ||
| | `casualtyComponents` | Contract components with no faithful target representation: `{dspackId, attempted, class, reason}` — documented and warned, not emitted | **judgment** | | ||
| | `intentionallyOmitted` | Ids deliberately not mapped (not casualties either). Must stay documented, never silent | **judgment** | | ||
| | `surfaceSynthesis` | Which synthesized primitives the surface emitter uses for text leaves (`textComponent`/`textProp`) and for wrapping multiple children in single-child slots (`wrapComponent`/`wrapChildrenProp`) | mechanical once `synthesized` is decided | | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
DX-2 companion (per the accepted RFC §6 DX-2: "emit-profile guide in dspack-emit, linked from the main one").
astryx-profile.tsas the working external reference, and the in-reposhadcnProfilereserved for ecosystem-canonical contracts), the fullProfileanatomy with mechanical-vs-judgment labeling, the three judgment calls (what synthesizes, what's a casualty, how compounds flatten), and validation viatransform/emitSurface.transform,emitSurface,validateCatalog,shadcnProfile,Profileall exported), and the external-authoring claim verified against the studio's real profile.Docs only — no engine or profile changes.
🤖 Generated with Claude Code