chore: change boxel-ui to flat directory structure

.claude/skills/gts-component-conventions/SKILL.md

@@ -49,7 +49,7 @@ box-shadow: 0 0 0 0.125rem var(--c); /* was 2px */
 
 ### 3. Save hardcoded colors as CSS variables
 
-Never ship a raw hex/rgb in a component. If a color recurs across components, promote it to a shared token in `packages/boxel-ui/addon/src/styles/variables.css`; if it's truly local, define a component-scoped custom property. Falling back to another variable is fine (`var(--token, var(--other))`); a hardcoded literal fallback is not.
+Never ship a raw hex/rgb in a component. If a color recurs across components, promote it to a shared token in `packages/boxel-ui/src/styles/variables.css`; if it's truly local, define a component-scoped custom property. Falling back to another variable is fine (`var(--token, var(--other))`); a hardcoded literal fallback is not.
 
 Reuse an existing semantic token before inventing a new one, and **name tokens by role, not by hue**. A color named for its appearance (`--boxel-teal-ink`, `--boxel-dark-teal`) is a palette primitive; a color named for its job (`--boxel-highlight`, `--boxel-highlight-hover`) is what components should reference.
 

.github/workflows/ci-host.yaml

@@ -385,7 +385,7 @@ jobs:
       # The env-mode host dist (with realm-server.ci.localhost URLs
       # baked in by environment.js) is built once in test-web-assets and
       # downloaded here, avoiding a per-shard rebuild. The artifact
-      # bundles boxel-icons/dist, boxel-ui/addon/dist, packages/host/dist,
+      # bundles boxel-icons/dist, boxel-ui/dist, packages/host/dist,
       # and the build manifest.
       - name: Download test web assets
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1

.github/workflows/ci-lint.yaml

@@ -51,7 +51,7 @@ jobs:
       - name: Lint Boxel UI
         if: ${{ !cancelled() }}
         run: pnpm run lint
-        working-directory: packages/boxel-ui/addon
+        working-directory: packages/boxel-ui
       - name: Lint Host
         # Runs BEFORE Build Boxel UI so host type-checks against the Boxel UI
         # source, exactly as local development does (declarations/ is never
@@ -68,11 +68,11 @@ jobs:
         # To faciliate linting of projects that depend on Boxel UI
         if: ${{ !cancelled() }}
         run: pnpm run build
-        working-directory: packages/boxel-ui/addon
+        working-directory: packages/boxel-ui
       - name: Lint Boxel UI Test App
         if: ${{ !cancelled() }}
         run: pnpm run lint
-        working-directory: packages/boxel-ui/test-app
+        working-directory: packages/boxel-ui/docs-app
       - name: Lint Matrix
         if: ${{ !cancelled() }}
         run: pnpm run lint

.github/workflows/ci.yaml

@@ -103,6 +103,7 @@ jobs:
               - *shared
               - 'packages/boxel-icons/**'
               - 'packages/boxel-ui/**'
+              - 'packages/boxel-ui/docs-app/**'
             matrix:
               - *shared
               - 'packages/base/**'
@@ -340,7 +341,10 @@ jobs:
           SKIP_ICONS_BUILD: ${{ steps.icons-cache.outputs.cache-hit }}
       - name: Run test suite
         run: pnpm test
-        working-directory: packages/boxel-ui/test-app
+        working-directory: packages/boxel-ui
+      - name: Run docs app test suite
+        run: pnpm test
+        working-directory: packages/boxel-ui/docs-app
 
   boxel-ui-raw-icon-changes-only:
     name: Boxel UI ensure raw icon changes only
@@ -355,7 +359,7 @@ jobs:
       - uses: ./.github/actions/init
       - name: Rebuild boxel-ui icons
         run: pnpm rebuild:icons
-        working-directory: packages/boxel-ui/addon
+        working-directory: packages/boxel-ui
       - name: Fail if generated icons have been changed without underlying raw icon changing
         run: git diff --exit-code
 
@@ -850,7 +854,7 @@ jobs:
         working-directory: packages/boxel-icons
       - name: Build Boxel UI
         run: pnpm run build
-        working-directory: packages/boxel-ui/addon
+        working-directory: packages/boxel-ui
       - name: Build host dist
         run: pnpm build
         working-directory: packages/host

.github/workflows/test-web-assets.yaml

@@ -75,7 +75,7 @@ jobs:
           key: ${{ steps.keys.outputs.cache_key }}
           path: |
             packages/boxel-icons/dist
-            packages/boxel-ui/addon/dist
+            packages/boxel-ui/dist
             packages/host/dist
             .ci/test-web-assets/manifest.json
 
@@ -133,7 +133,7 @@ jobs:
           key: ${{ steps.keys.outputs.cache_key }}
           path: |
             packages/boxel-icons/dist
-            packages/boxel-ui/addon/dist
+            packages/boxel-ui/dist
             packages/host/dist
             .ci/test-web-assets/manifest.json
 
@@ -143,7 +143,7 @@ jobs:
           name: ${{ steps.keys.outputs.artifact_name }}
           path: |
             packages/boxel-icons/dist
-            packages/boxel-ui/addon/dist
+            packages/boxel-ui/dist
             packages/host/dist
             .ci/test-web-assets/manifest.json
           retention-days: 7

AGENTS.md

@@ -52,13 +52,13 @@
 
 - No tests
 
-### packages/boxel-ui/addon, packages/boxel-ui/test-app
+### packages/boxel-ui, packages/boxel-ui/docs-app
 
 - Addon functionality is tested via sibling test-app directory
-- `cd packages/boxel-ui/addon && pnpm start` to start a process that will watch files and automatically rebuild the addon
-- `cd packages/boxel-ui/test-app && pnpm start` to start a process that will watch files and automatically rebuild the test-app
+- `cd packages/boxel-ui && pnpm start` to start a process that will watch files and automatically rebuild the addon
+- `cd packages/boxel-ui/docs-app && pnpm start` to start a process that will watch files and automatically rebuild the test-app
 - Run all tests
-  `cd packages/boxel-ui/test-app && ember test --path dist`
+  `cd packages/boxel-ui/docs-app && ember test --path dist`
 - To run a subset of the tests:
   `ember test --path dist --filter "some text that appears in module name or test name"`  
   Note that the filter is matched against the module name and test name, not the file name! Try to avoid using pipe characters in the filter, since they can confuse auto-approval tool use filters set up by the user.
@@ -92,7 +92,7 @@
 #### CSS Guidance
 
 - Use scalable units such as rem
-- Use CSS variables from packages/boxel-ui/addon/src/styles/variables.css
+- Use CSS variables from packages/boxel-ui/src/styles/variables.css
 
 #### Iterating on host tests with the Chrome MCP server
 

QUICKSTART.md

@@ -30,7 +30,7 @@ To build the entire repository and run the application, follow these steps:
 4. Build the boxel-ui addon:
 
    ```zsh
-   cd ./packages/boxel-ui/addon
+   cd ./packages/boxel-ui
    pnpm rebuild:icons
    pnpm build
    ```

README.md

@@ -18,9 +18,9 @@ For a quickstart, see [here](./QUICKSTART.md)
 
 `packages/realm-server` is a node app that serves the realm as an HTTP server, as well as, it can also host the runtime application for its own realm.
 
-`packages/boxel-ui/addon` is the UI components Ember addon
+`packages/boxel-ui` is the UI components Ember addon
 
-`packages/boxel-ui/test-app` is the test suite and component explorer for boxel-ui, deployed at [boxel-ui.stack.cards](https://boxel-ui.stack.cards)
+`packages/boxel-ui/docs-app` is the test suite and component explorer for boxel-ui, deployed at [boxel-ui.stack.cards](https://boxel-ui.stack.cards)
 
 `packages/matrix` is the docker container for running the matrix server: synapse, as well as tests that involve running a matrix client.
 
@@ -109,7 +109,7 @@ Make sure that you have created a matrix user for the base and experiments realm
 
 In order to run the ember-cli hosted app:
 
-1. `pnpm build` in the boxel-ui/addon workspace to build the boxel-ui addon.
+1. `pnpm build` in the boxel-ui workspace to build the boxel-ui addon.
 2. `pnpm start` in the host/ workspace to serve the ember app.
 3. `mise run dev` from the repo root to serve the base and experiments realms -- this will also allow you to switch between the app and the tests without having to restart servers). This expects the Ember application to be running at `https://localhost:4200`, if you’re running it elsewhere you can specify it with `HOST_URL=http://localhost:5200 mise run dev`.
 
@@ -525,7 +525,7 @@ Matrix requires an SMTP server in order to send emails. In order to facilitate t
 
 There is a ember-freestyle component explorer available to assist with development. In order to run the freestyle app:
 
-1. `cd packages/boxel-ui/test-app`
+1. `cd packages/boxel-ui/docs-app`
 2. `pnpm start`
 3. Visit http://localhost:4220/ in your browser
 
@@ -652,7 +652,7 @@ To run the `packages/realm-server/` workspace tests start:
 
 ### Boxel UI
 
-1. `cd packages/boxel-ui/test-app`
+1. `cd packages/boxel-ui/docs-app`
 2. `pnpm test` (or `pnpm start` and visit http://localhost:4220/tests to run tests in the browser)
 
 ### Matrix tests

docs/spec.md

@@ -8,8 +8,8 @@ At its core, a Spec links to an exported definition in modules via **Code Ref**
 
 ```typescript
 {
-  module: string;  // Path to the module file (e.g., './my-component.gts')
-  name: string;    // Export name (e.g., 'MyComponent')
+  module: string; // Path to the module file (e.g., './my-component.gts')
+  name: string; // Export name (e.g., 'MyComponent')
 }
 ```
 
@@ -18,21 +18,21 @@ When a module is edited (for example, if a definition is renamed), the spec migh
 ## Why We Need Specs
 
 - **Search for instance creation** - Enable discovery and instantiation of available components. Code refs are not searchable unless wrapped inside a card instance (a spec) which is then indexed and can benefit from all search capabilities. This makes field definitions searchable as well.
-- **Packaging of listings** - Code packaging in bundles occurs via linksToMany specs. The installation process looks for modules and code refs to copy during installation. 
+- **Packaging of listings** - Code packaging in bundles occurs via linksToMany specs. The installation process looks for modules and code refs to copy during installation.
 - **Link to examples** - Provide interactive demonstrations and usage patterns
 - **Documentation for code** - Maintain up-to-date, validated documentation connected to implementation
 
 ## Different Spec Types
 
-Code categorization is endless, so we focus on a subset of exported code that interests us within the Boxel ecosystem. 
+Code categorization is endless, so we focus on a subset of exported code that interests us within the Boxel ecosystem.
 
 The Boxel ecosystem supports five distinct spec types:
 
-- **`card`** 
-- **`field`** 
-- **`component`** 
-- **`app`** 
-- **`command`** 
+- **`card`**
+- **`field`**
+- **`component`**
+- **`app`**
+- **`command`**
 
 Each spec type has specific characteristics and use cases:
 
@@ -41,12 +41,14 @@ Each spec type has specific characteristics and use cases:
 **Purpose**: Document card definitions - the ultimate sharing unit of the Boxel ecosystem.
 
 **Characteristics**:
+
 - Can have multiple view templates (isolated, fitted, embedded, edit)
 - Often contain fields and computed properties
 - May extend other cards through inheritance
-- Support `linkedExamples` 
+- Support `linkedExamples`
 
 **Example Use Cases**:
+
 - `Author` - Author profile card with bio and social links
 - `Contact` - Contact information card for CRM systems
 - `BlogPost` - Blog post card with content and metadata
@@ -57,12 +59,14 @@ Each spec type has specific characteristics and use cases:
 **Purpose**: Document field definitions used within cards.
 
 **Characteristics**:
+
 - Only support `containedExamples` (embedded within the spec)
 - May be primitive (string, number, boolean) or composite
-- TBD: display of primitive contained examples 
+- TBD: display of primitive contained examples
 - May extend other fields through inheritance
 
 **Example Use Cases**:
+
 - `SocialMediaLink` - Composite field for social platform data
 - `MaybeBase64Field` - String field with base64 encoding capabilities
 - `TextAreaField` - Multi-line text input field
@@ -73,12 +77,14 @@ Each spec type has specific characteristics and use cases:
 **Purpose**: Document reusable UI components that don't represent data, so AI agents and developers can discover them by searching the catalog instead of needing a per-component skill.
 
 **Characteristics**:
+
 - Only when it extends Glimmer Component
 - Potentially includes reactive data loading resources from ember-resources
 - API documentation, an example, and CSS variables live in the `readMe` markdown field
 - `cardDescription` is the keyword-rich one-liner the agent matches against — keep it concrete (e.g. "Form text input with validation states") rather than abstract
 
 **Example Use Cases**:
+
 - `CardsGrid` - Responsive grid layout component for card collections
 - `FilterDropdown` - Multi-select dropdown component for filtering
 - `Pill` - Badge component for displaying tags and statuses
@@ -87,7 +93,7 @@ Each spec type has specific characteristics and use cases:
 #### Boxel-UI Component Specs
 
 All `@cardstack/boxel-ui` components ship a generated Spec card. The
-generator (`packages/boxel-ui/addon/bin/generate-component-specs.mjs`)
+generator (`packages/boxel-ui/bin/generate-component-specs.mjs`)
 walks each component's `usage.gts` file, extracts the `FreestyleUsage`
 metadata (arguments, description, example, CSS variables), and emits a
 Spec JSON with:
@@ -116,7 +122,7 @@ the deployed commit.
    `<FreestyleUsage>` block has a `@description='…'` attribute and
    complete `<Args.X>` documentation.
 2. (Optional, but recommended) Run
-   `pnpm --dir packages/boxel-ui/addon generate:component-specs` locally
+   `pnpm --dir packages/boxel-ui generate:component-specs` locally
    to inspect the resulting spec content and have your local
    realm-server reindex it. Requires
    `pnpm --dir packages/catalog catalog:setup` to have run at least
@@ -150,12 +156,14 @@ the deployed commit.
 **Purpose**: Document application-level cards that serve as entry points, typically when other cards are queried within them.
 
 **Characteristics**:
-- Extends AppCard which displays in a wide view 
-- Often contain more than one query 
-- Often use navigation components like tabs or sidebars 
-- Support `linkedExamples` 
+
+- Extends AppCard which displays in a wide view
+- Often contain more than one query
+- Often use navigation components like tabs or sidebars
+- Support `linkedExamples`
 
 **Example Use Cases**:
+
 - `BlogApp` - Blog content management system
 - `PreschoolCRMApp` - Customer relationship management for preschools
 - `SprintPlanner` - Sprint planning applications
@@ -165,11 +173,13 @@ the deployed commit.
 **Purpose**: Document executable commands within the system.
 
 **Characteristics**:
-- Represent actions within a command palette 
+
+- Represent actions within a command palette
 - Imperative code that doesn't depend on data loading in a component
-- Have access to host code via boxel-host commands 
+- Have access to host code via boxel-host commands
 
 **Example Use Cases**:
+
 - `GenerateReadmeSpecCommand` - Generate documentation for spec cards
 - `SearchCardsByQueryCommand` - Advanced card search with filtering
 - `PatchCardInstanceCommand` - Update card instance data

eslint/data-test-selectors.cjs

@@ -9,7 +9,7 @@
 // plain `data-*` attribute for things you actually select on.
 //
 // Shared by the root `.eslintrc.js` and by packages whose own config is
-// `root: true` (e.g. `packages/host`, `packages/boxel-ui/addon`), which do not
+// `root: true` (e.g. `packages/host`, `packages/boxel-ui`), which do not
 // inherit the root config and so must re-declare these selectors themselves.
 const DATA_TEST_MESSAGE =
   "Don't select on `data-test-*`: it's a test-only attribute (host builds strip it in production; card code keeps it but coupling to a test hook is fragile). Use a plain `data-*` attribute (e.g. `[data-foo]`) for functional selectors.";

mise-tasks/build/ui

@@ -9,4 +9,4 @@ else
   pnpm --dir packages/boxel-icons build
 fi
 
-pnpm --dir packages/boxel-ui/addon build
+pnpm --dir packages/boxel-ui build

mise-tasks/build/worktree-types

@@ -7,6 +7,6 @@ echo "Building @cardstack/boxel-icons..."
 pnpm --dir packages/boxel-icons build
 
 echo "Building @cardstack/boxel-ui (includes type declarations)..."
-pnpm --dir packages/boxel-ui/addon build
+pnpm --dir packages/boxel-ui build
 
 echo "Done — worktree type declarations are ready for pnpm lint"

package.json

@@ -6,14 +6,14 @@
   },
   "scripts": {
     "build:boxel-host": "pnpm run build-common-deps && cd packages/host && NODE_OPTIONS='--max_old_space_size=8192' pnpm build:production",
-    "build-common-deps": "cd packages/boxel-icons && pnpm build && cd ../.. && cd packages/boxel-ui/addon && pnpm build && cd ../../..",
+    "build-common-deps": "cd packages/boxel-icons && pnpm build && cd ../.. && cd packages/boxel-ui && pnpm build && cd ../../..",
     "ci:failures": "node ./scripts/ci-failures.js",
     "clear-caches": "find . -name 'node_modules' -type d -prune -exec rm -rf {} \\; && rm -rf $TMPDIR/embroider",
     "deploy:boxel-host": "pnpm run build-common-deps && cd packages/host && BASE_REALM_HOSTING_DISABLED=true NODE_OPTIONS='--max_old_space_size=8192' pnpm exec ember deploy",
     "deploy:boxel-host:preview-staging": "pnpm run build-common-deps && cd packages/host && BASE_REALM_HOSTING_DISABLED=true NODE_OPTIONS='--max_old_space_size=8192' pnpm exec ember deploy s3-preview-staging --verbose",
     "deploy:boxel-host:preview-production": "pnpm run build-common-deps && cd packages/host && BASE_REALM_HOSTING_DISABLED=true NODE_OPTIONS='--max_old_space_size=8192' pnpm exec ember deploy s3-preview-production --verbose",
-    "deploy:boxel-ui": "pnpm run build-common-deps && cd packages/boxel-ui/test-app && pnpm exec ember deploy",
-    "deploy:boxel-ui:preview-staging": "pnpm run build-common-deps && cd packages/boxel-ui/test-app && pnpm exec ember deploy s3-preview-staging --verbose",
+    "deploy:boxel-ui": "pnpm run build-common-deps && cd packages/boxel-ui/docs-app && pnpm exec ember deploy",
+    "deploy:boxel-ui:preview-staging": "pnpm run build-common-deps && cd packages/boxel-ui/docs-app && pnpm exec ember deploy s3-preview-staging --verbose",
     "lint": "pnpm run --filter './packages/**' --if-present -r lint",
     "lint:fix": "pnpm run --filter './packages/**' --if-present -r lint:fix",
     "openrouter:sync": "OPENROUTER_REALM_URL=${OPENROUTER_REALM_URL:-https://localhost:4201/openrouter/} pnpm --filter @cardstack/realm-server sync-openrouter-models",

packages/ai-bot/tsconfig.json

@@ -38,8 +38,8 @@
         "../base/*.d.ts",
         "../base/*"
       ],
-      "@cardstack/boxel-ui": ["../boxel-ui/addon"],
-      "@cardstack/boxel-ui/*": ["../boxel-ui/addon/*"]
+      "@cardstack/boxel-ui": ["../boxel-ui"],
+      "@cardstack/boxel-ui/*": ["../boxel-ui/*"]
     },
     "types": ["@cardstack/local-types"]
   },

packages/base/tsconfig.json

@@ -22,8 +22,8 @@
     "strict": true,
     "experimentalDecorators": true,
     "paths": {
-      "@cardstack/boxel-ui": ["../boxel-ui/addon/declarations"],
-      "@cardstack/boxel-ui/*": ["../boxel-ui/addon/declarations/*"],
+      "@cardstack/boxel-ui": ["../boxel-ui/declarations"],
+      "@cardstack/boxel-ui/*": ["../boxel-ui/declarations/*"],
       "@cardstack/boxel-host/tools/*": ["../host/app/tools/*"],
       "@cardstack/boxel-host/commands/*": ["../host/app/tools/*"]
     }

packages/billing/tsconfig.json

@@ -38,8 +38,8 @@
         "../base/*.d.ts",
         "../base/*"
       ],
-      "@cardstack/boxel-ui": ["../boxel-ui/addon"],
-      "@cardstack/boxel-ui/*": ["../boxel-ui/addon/*"],
+      "@cardstack/boxel-ui": ["../boxel-ui"],
+      "@cardstack/boxel-ui/*": ["../boxel-ui/*"],
       "*": ["types/*"]
     },
     "types": ["@cardstack/local-types"]