@elyx-design/codex-plugin 0.0.0-bootstrap.0 → 0.0.1-nightly.16119.gf080cb874

package/skills/elyx/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: elyx
+description: Elyx is a design tool with local, AI-friendly `.elyx` files for screens, components, layouts, flows, and design systems. MANDATORY Use this skill before you read, reason about, or answer any question about Elyx or `.elyx` files. That includes authoring, editing, validating, inspecting, reviewing, refactoring, comparing, and recommending changes, and read-only analysis that produces no edit. Do not reason about `.elyx` files from source text alone. Imports, instances, overrides, and layout resolve only through the `elyx` CLI.
+---
+
+## How to work in Elyx
+
+This skill uses the `elyx` command from the public `@elyx-design/cli` npm
+package. Before you work with Elyx files, run `elyx --help` to confirm that
+`elyx` is on your `PATH`. If it is not, ask the user to install it. For
+example:
+
+```bash
+npm install --global @elyx-design/cli
+```
+
+For the authoritative list of flags, run `elyx --help` or `elyx <subcommand> --help`.
+
+### Use `find` and `tree` to see the resolved scene
+
+Use `find` and `tree` to read the scene after imports, instances, overrides, layout, and geometry resolve:
+
+- `find --ref`: get the final data and bounds of one layer by its exact ref.
+  `elyx find path/to/file.elyx --ref ctaButton`
+
+- `find --at`: get the topmost rendered layer at a board-space point.
+  `elyx find path/to/file.elyx --at 420,180`
+
+- `find --in`: get the layers that intersect a board-space rectangle, or that the rectangle contains.
+  `elyx find path/to/file.elyx --in 0,0,800,600`
+  `elyx find path/to/file.elyx --in 0,0,800,600 --contain --click-through`
+
+- `tree`: get the semantic layer tree of a file, or of one internal source ref, with children, instance source references, layout, position, constraints, text, and style.
+  `elyx tree path/to/file.elyx --ref OnboardingWelcome`
+  `elyx tree path/to/file.elyx --ref OnboardingWelcome --depth full`
+
+The results use these conventions:
+
+- `localBounds` is geometry in the layer's own space. `absoluteBounds` is geometry in board space.
+- In the tree, `position` is the resolved local placement. `constraints` are the stored values that drive layout.
+- A value bound to a design token appears as `{"value": …, "token": "<file>#<group>.<member>"}`. The token is the same in every context.
+- `instanceOf` gives an instance's source `file`, `symbol`, and `variant`.
+- Slot nodes include `slot: true`. Other nodes omit it.
+- The tree depth accepts `shallow`, `full`, or a non-negative integer. An integer limits how many instance boundaries the tree crosses.
+
+### Name things the way users do
+
+When you describe or name Elyx objects, follow these rules:
+
+- Say “layer”, “component”, or “screen” for visual design objects.
+- The declaration symbol before `=` is the layer’s name. Make its leaf name semantic, valid Elyx syntax, and consistent with the project. Do not add a separate `name:` property.
+- Say “symbol” for source identity, imports, references, arguments, and renames.
+- Say “token” for design tokens. Say “variable” only for other reusable values that are not layers.
+
+### 1. Orient
+
+Before you assume anything from source examples, use `elyx man` to learn Elyx syntax, concepts, properties, and component semantics. `elyx man` prints the overview manual. `elyx man <topic-or-schema-path>` prints one topic, such as `elyx man components`, `elyx man instance`, or `elyx man frame.width`. If you do not know the right path, run `elyx man --list`.
+
+### 2. Author
+
+The project usually already has a design system and its own file vocabulary.
+Reuse and import its existing building blocks. Do not build a parallel system.
+
+Prefer composition to recreation. Import and instantiate existing components
+instead of rebuilding them from raw layers.
+
+To learn how Elyx projects are organized, run `elyx man project-structure`.
+To learn component composition and override semantics, run `elyx man components`, `elyx man instance`, `elyx man variants`, and `elyx man slots`.
+
+When you add or change structure, follow these rules:
+
+- Before you write a property you have not used yet, read its documentation. Elyx ignores a property it does not know.
+- Import shared components, tokens, and blocks where you can.
+- Use stacks and `.auto` sizing for normal interface layout. The `frame.layout` documentation describes them.
+- Keep overrides local and intentional.
+- For icons and other vector artwork, write a small SVG file and import it as an asset. The `assets` documentation shows how, including tinting it with `fill`. Do not use Unicode symbols as icons, because the font may have no glyph for them.
+- Rename symbols one source file at a time. Before you move on, repair the local references and all direct and transitive consumers.
+- Before you reason about instances or overrides, read the resolved structure and geometry from the tree.
+
+#### Leave space between canvas items
+
+When you place separate screens, frames, or component examples on a board,
+leave at least 48px between the edges of adjacent items. Aim for a gap of at
+least 20% of the larger item’s size along the spacing direction. That is the
+width for items side by side, and the height for items stacked vertically. For
+example, two 1920px-wide screens side by side need about 384px or more between
+them, not 48px.
+
+The 20% target is a guideline, not a rigid rule. Keep spacing consistent
+within groups, and leave room for frame titles. To measure gaps, use the
+resolved bounds of the items. To review the arrangement, render it. This
+guidance covers the space between distinct canvas items. It does not cover
+padding or gaps inside a screen or component, or intentional overlaps. Do not
+re-space unrelated content unless the user asks.
+
+### 3. Render the result
+
+```bash
+rg -n --glob '*.elyx' '@context\s*\(' .    # find the context axes and values in the workspace
+elyx render path/to/file.elyx -o out.png
+elyx render path/to/file.elyx --context theme=dark -o out-dark.png
+elyx render path/to/file.elyx --context theme=dark --extra-file path/to/theme-dark.elyx -o out-dark.png
+elyx render path/to/file.elyx --ref <name> --context theme=dark --context lang=pt -o out.png
+```
+
+Use `render` whenever the visual result matters. Do not assume that a `.elyx` change is correct from its source text alone.
+
+To render one layer, use `--ref <name>`. To render with custom contexts without changing the source file, repeat `--context axis=value`. To load files that the rendered file does not import, repeat `--extra-file <file>`. A `--context` selection changes the output only after the file that declares the context is loaded. Without the matching `--extra-file`, the render silently falls back to the default values. Before you render, search the workspace's `@context` annotations to learn the available axes and values.
+
+The `render` scale defaults to 1. Add `--scale 2` only for fine detail, because it produces four times the pixels.
+
+### 4. Check the changed files
+
+When your edits are done, normalize each changed file in place. Then check the
+changed files for errors and warnings.
+
+```bash
+elyx normalize -w path/to/file.elyx
+elyx diagnostics path/to/file.elyx   # with no target, checks the whole project
+```
+
+Check the smallest scope that covers the changed files. Resolve every warning,
+or account for it explicitly.
+
+If normalization reports that it fell back to syntax-only formatting, the file
+loaded with problems, so it was only formatted. Fix the problems it lists,
+then normalize the file again.

package/skills/elyx-code/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: elyx-code
+description: Translate between Elyx designs and web code. Use this skill to implement or update code from an Elyx design, to create or update an Elyx design from code, to import an existing app into Elyx, or to keep linked design and code in sync.
+---
+
+# Elyx and code
+
+For Elyx inspection, language documentation, authoring, and validation, use the `elyx` skill. For the target project's framework, components, and checks, follow its `AGENTS.md` and existing code conventions.
+
+## Establish the correspondence
+
+- Identify the requested direction and scope: a component, a screen, a design system, or an app. For an update, inspect the changed side before you edit its counterpart, including its diff when one is available. Keep unrelated states and layers intact.
+- Look for existing `meta.code` links, code backlinks, component implementations, tokens, assets, and nearby examples. Treat a link as a lead to verify on both sides, not as proof that everything still matches.
+- For an existing Elyx target, run `elyx tree <file> --ref <ref> --depth shallow` and `elyx render <file> --ref <ref> -o out.png` with the relevant context. To see through instances, increase the tree depth. The tree shows inherited `meta` such as `meta.code`, token bindings, and `instanceOf` with its `variant`. Source text alone cannot show the final layout or overrides.
+- To inspect or render a descendant inside an instance, reuse a non-null `target` from `find` or `tree` output. Pass its `filePath` as the input file, its `sourceRef` as `--ref`, and its `overridePath`, when present, as `--override-path`. Do not infer an instance occurrence from its display path.
+- For feedback on the code side, look in the repo's scripts, docs, and nearby stories for an existing route, preview, or component harness that shows the relevant state. If one is practical to use, compare appearance and behavior with the browser or component tools you have. Accessibility and computed-style feedback can explain what a screenshot cannot. Do not add a browser dependency only for this step. If you cannot inspect the running code, work from source and the existing project checks, and say what you could not observe.
+
+## Elyx to web concept map
+
+Use these analogies as a starting point. Then follow the target framework and the resolved design.
+
+| Elyx | Web code analogy | Check |
+| --- | --- | --- |
+| Stack `layout: {direction: .row, item-gap: 8px}` | `display: flex; flex-direction: row; gap: 8px` | Preserve order, alignment, wrapping, and responsive behavior. Nested stacks or a grid may fit the code better. |
+| Freeform children with `left` and `top` | A `position: relative` parent and `position: absolute` children for intentional overlap | Coordinates are relative to the parent. Canvas placement does not need to become app positioning. |
+| `.auto`, percentages, `overflow` | Intrinsic sizing, parent-relative percentages, CSS overflow | Elyx clips by default. CSS overflow defaults to visible. A freeform frame without a size can collapse. |
+| Tokens | CSS custom properties, Tailwind theme tokens, or the project's token system | Preserve roles, aliases, and units. |
+| `@context` | Theme selectors, locale state, or responsive breakpoints | Inspect which tokens or structural variants change in that context. |
+| Component instance (`frame : source`) | A component call, such as `<Card />` | Instance overrides become values that are passed or composed at that use site, not a copied implementation. |
+| `@variant` | A prop, state, or style variant in the component API | The Elyx variant inherits its base. Inspect the actual code API before you choose a prop. |
+| `slot: .true` on a frame | React `<Card>{content}</Card>` for one region. A named `header` prop or component composition for several regions. | Preserve the region's layout. Elyx source children are example content that instances start with. Decide whether the code supplies a default or leaves the content to callers. |
+| `connections: {target: ...}` | Navigation or a transition to another screen, component, or state | The target records the intended destination. Inspect the code for the event, guard, and transition behavior. |
+
+## From Elyx to code
+
+- Reuse the project's components and design tokens. Match a token's semantic role as well as its value. Where a corresponding code token exists, preserve the token binding. If none exists, add a suitable token by the project's conventions, or explain the unresolved mapping. Inspect a component's actual API before you choose props.
+- Translate the layout intent into the project's normal responsive layout primitives. Preserve content, assets, typography, and the represented states. For interactive controls, use the project's behavior patterns to preserve selection rules, initial state, disabled behavior, and keyboard access.
+- For a flow, read the `connections` declarations in the Elyx source, and follow their targets across files. Component inspection alone does not find them. Map each meaningful destination and branch to the project's routes or state transitions. Then verify in code the interaction that activates each one. A destination does not need to appear on the current board for its connection to be valid.
+- For an update, follow the existing design-to-code correspondence. Change the affected implementation instead of recreating it.
+
+## From code to Elyx
+
+- Before you create Elyx tokens, components, contexts, or links, inventory the relevant existing ones. Reuse them where they express the code's roles and structure. When you import a design system, set up the shared tokens and theme contexts before you bind components to them. Preserve the code's base and semantic token layers and its resolved lengths. Verify that representative aliases resolve in each theme.
+- Use components for reused controls, variants for meaningful differences, slots for composable regions, and instances for screen composition. Use stacks for normal UI flow, and freeform placement for intentional overlap or canvas arrangement.
+- Represent one specific, valid UI state. For conditional or data-driven UI, choose representative states. Do not combine branches into a screen that the app cannot show. Capture theme, language, and responsive differences with the project's existing conventions, and with Elyx contexts or variants where they fit.
+- When the code has a meaningful flow between represented screens, panels, or states, put a connection on the source control, and target the corresponding Elyx layer. For example, after you import `"./checkout.elyx" as Checkout`, a continue button can use `connections: {target: Checkout.paymentScreen}`. Keep destinations as references, including across files. To see the whole flow at once, use an overview with `draw-connections: .true`.
+- For an update, edit the linked declaration or instance that corresponds to the code change. Preserve the shared component and the other instances, unless the code change affects them too.
+
+For example, this code defines a shared default, and one caller supplies a different title:
+
+```tsx
+function PlanCard({ title = "Plan" }: { title?: string }) {
+  return <article>{title}</article>
+}
+<PlanCard title="Starter" />
+```
+
+The linked Elyx component carries the default. The caller's value belongs on its instance:
+
+```elyx
+export planCard = frame {
+  children: title,
+  title = text {contents: "Plan"}
+}
+starterCard = frame : planCard {
+  title {contents: "Starter"}
+}
+```
+
+If only that call site changes, update `starterCard`. If the component default changes, update `planCard`. Check the resolved instance before you edit either one.
+
+## Translation details that are easy to miss
+
+Watch for these differences:
+
+- A stacked child ignores `left` and `top`.
+- When content intentionally extends beyond a frame, such as a shadow, use `overflow: .visible` in Elyx.
+- Elyx text `letter-spacing` is a percentage of the font size. A positive `line-height` is a multiplier, and `0` means automatic.
+- An Elyx variant is an instance of its base with overrides. `@context` selects alternate tokens or contextual variants. By itself, it does not define a web breakpoint or a component prop.
+
+## Link and check the result
+
+- When you have verified the correspondence, put `meta.code` on the narrowest useful Elyx declaration. Use repo-relative paths and stable symbols, as in this pair.
+
+  In `elyx/design/blocks/planCard.elyx`, on the `planCard` declaration:
+
+  ```elyx
+  meta: {code: "src/components/blocks/plan-card.tsx#PlanCard"}
+  ```
+
+  If the project uses backlinks, above `PlanCard` in the code:
+
+  ```tsx
+  // @elyx elyx/design/blocks/planCard.elyx#planCard
+  ```
+
+  To go from design to code, open the linked implementation. To go from code to design, search for its backlink or a matching `meta.code`. When a path or symbol moves, update the link. Instances inherit source metadata, so do not copy the component link onto them.
+- Render the affected states and contexts. When your edits are done, normalize the changed Elyx files and run full diagnostics on them. Run the project's relevant code checks. If a code preview is available, compare the changed state's appearance and behavior with the design. Report material gaps or unverified states.