### Build and Start Frontile Site

Source: https://github.com/josemarluedke/frontile/blob/main/AGENTS.md

Builds or starts the Frontile documentation site. Useful for previewing documentation changes.

```bash
cd site && pnpm build
```

```bash
cd site && pnpm start
```

--------------------------------

### Install Frontile Packages

Source: https://github.com/josemarluedke/frontile/blob/main/docs/index.md

Install Frontile and its theme package using pnpm.

```sh
pnpm install frontile @frontile/theme
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/josemarluedke/frontile/blob/main/site/README.md

Use this command to install all necessary project dependencies after cloning the repository.

```bash
pnpm install
```

--------------------------------

### Install Dependencies

Source: https://github.com/josemarluedke/frontile/blob/main/test-app/README.md

Install all project dependencies using npm.

```bash
npm install
```

--------------------------------

### Install Frontile Forms

Source: https://github.com/josemarluedke/frontile/blob/main/docs/migrations/forms-legacy.md

Remove the legacy package and install the new frontile and @frontile/theme packages.

```bash
# Remove the legacy package
npm uninstall @frontile/forms-legacy

# Install the new package
npm install frontile @frontile/theme
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/josemarluedke/frontile/blob/main/README.md

Commands to clone the Frontile repository, navigate into the directory, and install project dependencies using pnpm.

```sh
git clone https://github.com/josemarluedke/frontile.git
cd frontile
pnpm install
```

--------------------------------

### Start Development Server

Source: https://github.com/josemarluedke/frontile/blob/main/test-app/README.md

Start the Ember development server to run the application locally.

```bash
npm run start
```

--------------------------------

### Basic Modal Example

Source: https://github.com/josemarluedke/frontile/blob/main/packages/frontile/src/components/overlays/modal.md

A fundamental example demonstrating how to implement a basic modal with header, body, and footer. Use the `@isOpen` and `@onClose` arguments to control visibility. The modal can be closed by clicking the backdrop or the provided buttons.

```gts
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { action } from '@ember/object';
import { Modal } from 'frontile';
import { Button } from 'frontile';

export default class BasicModal extends Component {
  @tracked isOpen = false;

  @action toggle() {
    this.isOpen = !this.isOpen;
  }

  <template>
    <div class='flex flex-col gap-4'>
      <Button @onPress={{this.toggle}}>
        Open Modal
      </Button>

      <Modal @isOpen={{this.isOpen}} @onClose={{this.toggle}} as |m|>
        <m.Header>
          Basic Modal
        </m.Header>
        <m.Body>
          <p class='mb-4'>This is the main content of the modal. Modals are
            great for displaying important information, forms, or confirmation
            dialogs.</p>
          <p>The modal appears centered on the screen with a backdrop that can
            be clicked to close it.</p>
        </m.Body>
        <m.Footer @class='flex gap-2'>
          <Button @onPress={{this.toggle}}>
            Cancel
          </Button>
          <Button @intent='primary'>
            Confirm
          </Button>
        </m.Footer>
      </Modal>
    </div>
  </template>
}
```

--------------------------------

### Start Development Server

Source: https://github.com/josemarluedke/frontile/blob/main/AGENTS.md

Launch the development server for the 'test-app'. This command is used for local development and testing changes in real-time.

```bash
pnpm start  # Starts test-app dev server
```

--------------------------------

### Run Site Development Server

Source: https://github.com/josemarluedke/frontile/blob/main/CLAUDE.md

Starts the development server for the documentation site. Useful for previewing doc changes.

```bash
cd site && pnpm start
```

--------------------------------

### Install Theme Package

Source: https://github.com/josemarluedke/frontile/blob/main/docs/theming/overview.md

Install the theme package using Ember CLI.

```bash
ember install @frontile/theme
```

--------------------------------

### Complete Brand Theme Configuration

Source: https://github.com/josemarluedke/frontile/blob/main/docs/theming/configuration/customization.md

A full example demonstrating how to configure Frontile for a brand, including custom colors, fonts, and component styles.

```js
const { frontile } = require('@frontile/theme/plugin');

module.exports = frontile({
  defaultTheme: 'light',
  themes: {
    light: {
      colors: {
        // Purple brand color
        primary: {
          subtle: '#faf5ff',
          soft: '#c084fc',
          medium: '#9333ea',
          strong: '#581c87'
        },
        // Success remains green
        success: {
          subtle: '#f0fdf4',
          soft: '#86efac',
          medium: '#22c55e',
          strong: '#14532d'
        },
        // Custom orange warning
        warning: {
          subtle: '#fff7ed',
          soft: '#fdba74',
          medium: '#f97316',
          strong: '#7c2d12'
        }
      }
    },
    dark: {
      colors: {
        primary: {
          subtle: '#581c87',
          soft: '#9333ea',
          medium: '#a855f7',
          strong: '#f3e8ff'
        }
        // ... other colors
      }
    }
  }
});
```

```css
@import 'tailwindcss' source('../../');
@plugin "./../../frontile.js";
@import "@frontile/theme";

/* Load custom fonts */
@font-face {
  font-family: 'Poppins';
  src: url('/fonts/poppins-var.woff2') format('woff2');
  font-weight: 100 900;
  font-display: swap;
}

@theme {
  /* Typography */
  --font-header: 'Poppins', system-ui, sans-serif;
  --font-body: 'Poppins', system-ui, sans-serif;
  --font-label: 'Poppins', system-ui, sans-serif;

  /* Rounded design */
  --radius: 12px;
  --radius-xl: 20px;
  --radius-2xl: 24px;

  /* Slightly larger icons */
  --size-icon-sm: 16px;
  --size-icon-md: 20px;
  --size-icon-lg: 24px;

  /* Subtle opacity changes */
  --opacity-hover: .9;
  --opacity-disabled: .5;
}

/* Component customization */
:root {
  /* Wider modals */
  --modal-md: 36rem;
  --modal-lg: 52rem;
}
```

--------------------------------

### Component Examples with Theme Inverse

Source: https://github.com/josemarluedke/frontile/blob/main/docs/theming/configuration/theme-switching.md

Shows how Frontile components like Chip and ProgressBar automatically adapt to the 'theme-inverse' class. This example displays a project status section with various chips and a progress bar.

```gts
import { Button, Chip, ProgressBar } from 'frontile';

<template>
  <div class='space-y-6'>
    {{! Cards with status chips }}
    <div class='theme-inverse p-6 bg-surface-canvas rounded-lg'>
      <h4 class='text-header-sm text-neutral-strong mb-3'>Project Status</h4>
      <div class='flex flex-wrap gap-2 mb-4'>
        <Chip @intent='success'>Active</Chip>
        <Chip @intent='warning'>In Review</Chip>
        <Chip @intent='default'>Draft</Chip>
      </div>
      <ProgressBar @progress={{65}} @intent='primary' />
    </div>
  </div>
</template>
```

--------------------------------

### Install Forms-Legacy Package

Source: https://github.com/josemarluedke/frontile/blob/main/docs/migrations/changeset-form.md

This command sequence installs the forms-legacy package, which is part of the minimal-effort approach for migrating changeset forms.

```bash
npm uninstall @frontile/changeset-form
npm install @frontile/forms-legacy
# Keep: ember-changeset ember-changeset-validations

# Build the package
pnpm --filter forms-legacy build
```

--------------------------------

### Install Dependencies for Modern Forms

Source: https://github.com/josemarluedke/frontile/blob/main/docs/migrations/changeset-form.md

Remove deprecated packages and install the necessary frontile and valibot packages for the recommended migration approach.

```bash
npm uninstall @frontile/changeset-form @frontile/forms-legacy
npm uninstall ember-changeset ember-changeset-validations

npm install frontile @frontile/theme valibot
```

--------------------------------

### Complete Form Example

Source: https://github.com/josemarluedke/frontile/blob/main/packages/changeset-form/docs/changeset-form-usage.md

This example shows a full implementation of a form using ChangesetForm, including text inputs, textarea, select, checkbox group, radio group, and submit/reset buttons. It also displays the changeset's validation state.

```gts
import Component from '@glimmer/component';
import { ChangesetForm } from '@frontile/changeset-form';
import Button from '@frontile/buttons/components/button';
import { changeset } from 'ember-changesets';
import validateFormat from 'ember-changeset-validations/validators/format';
import validatePresence from 'ember-changeset-validations/validators/presence';

export const myValidations = {
  firstName: validatePresence(true),
  lastName: validatePresence(true),
  email: validateFormat({ type: 'email' }),
  countries: validatePresence(true)
};

export default class Demo extends Component {
  validations = myValidations;
  countries = [
    'Brazil',
    'India',
    'Israel',
    'Japan',
    'United Kingdom',
    'United States'
  ];

  model = {
    firstName: null,
    lastName: null,
    email: 'frontile@example.com',
    comments: 'Changeset forms are great! 🚀',
    countries: ['Brazil', 'United States'],
    coreValues: {
      hungry: true,
      humble: true,
      curious: true
    },
    favoriteMeal: 'lunch'
  };

  <template>
    {{#let (changeset this.model this.validations) as |changeset|}}
      <ChangesetForm @changeset={{changeset}} as |Form|>
        <Form.Input
          @label='First Name'
          @fieldName='firstName'
          placeholder='What is your first name?'
        />
        <Form.Input
          @label='Last Name'
          @fieldName='lastName'
          @containerClass='mt-4'
          placeholder='What is your family name?'
        />
        <Form.Input
          @label='Email Address'
          @fieldName='email'
          type='email'
          @containerClass='mt-4'
        />
        <Form.Textarea
          @label='Comments'
          @fieldName='comments'
          @containerClass='mt-4'
        />
        <Form.Select
          @label='Countries'
          @fieldName='countries'
          @isMultiple={{true}}
          @options={{this.countries}}
          @allowClear={{true}}
          @containerClass='mt-4'
          as |option|
        >
          {{option}}
        </Form.Select>
        <Form.CheckboxGroup
          @groupName='coreValues'
          @label='Core Values'
          @containerClass='mt-4'
          as |Checkbox|
        >
          <Checkbox @label='Hungry' @fieldName='hungry' />
          <Checkbox @label='Humble' @fieldName='humble' />
          <Checkbox @label='Curious' @fieldName='curious' />
        </Form.CheckboxGroup>
        <Form.RadioGroup
          @label='Favorite Meal'
          @containerClass='mt-4'
          @fieldName='favoriteMeal'
          as |Radio|
        >
          <Radio @label='Breakfast' @value='breakfast' />
          <Radio @label='Lunch' @value='lunch' />
          <Radio @label='Dinner' @value='dinner' />
        </Form.RadioGroup>
        <Button
          @type='submit'
          @intent='primary'
          disabled={{changeset.isInvalid}}
          class='mt-4'
        >
          Save
        </Button>
        <Button @type='reset' @appearance='outlined'>
          Reset
        </Button>
        <div class='mt-4'>
          <code>
            <p>isPristine: {{changeset.isPristine}}</p>
            <p>isValid: {{changeset.isValid}}</p>
            <p>isInvalid: {{changeset.isInvalid}}</p>
          </code>
        </div>
      </ChangesetForm>
    {{/let}}
  </template>
}
```

--------------------------------

### Nested Modals Example

Source: https://github.com/josemarluedke/frontile/blob/main/packages/frontile/src/components/overlays/modal.md

Demonstrates how to open multiple modals sequentially, with each modal maintaining its own focus trap and backdrop.

```gts
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { action } from '@ember/object';
import { Modal } from 'frontile';
import { Button } from 'frontile';

export default class NestedModals extends Component {
  @tracked firstModalOpen = false;
  @tracked secondModalOpen = false;
  @tracked thirdModalOpen = false;

  @action toggleFirst() {
    this.firstModalOpen = !this.firstModalOpen;
  }

  @action toggleSecond() {
    this.secondModalOpen = !this.secondModalOpen;
  }

  @action toggleThird() {
    this.thirdModalOpen = !this.thirdModalOpen;
  }

  @action closeAll() {
    this.thirdModalOpen = false;
    this.secondModalOpen = false;
    this.firstModalOpen = false;
  }

  <template>
    <div class='flex flex-col gap-4'>
      <Button @onPress={{this.toggleFirst}}>
        Open First Modal
      </Button>

      <!-- First Modal -->
      <Modal
        @isOpen={{this.firstModalOpen}}
        @onClose={{this.toggleFirst}}
        as |m|
      >
        <m.Header>First Modal</m.Header>
        <m.Body>
          <p class='mb-4'>This is the first modal. You can open another modal
            from here.</p>
          <p class='text-sm text-neutral-medium'>Notice how the backdrop becomes
            darker with each modal layer.</p>

          <!-- Second Modal -->
          <Modal
            @isOpen={{this.secondModalOpen}}
            @onClose={{this.toggleSecond}}
            @size='md'
            as |m|
          >
            <m.Header>Second Modal</m.Header>
            <m.Body>
              <p class='mb-4'>This is the second modal, opened from the first
                one.</p>
              <p class='text-sm text-neutral-medium'>You can continue nesting
                modals as needed.</p>

              <!-- Third Modal -->
              <Modal
                @isOpen={{this.thirdModalOpen}}
                @onClose={{this.toggleThird}}
                @size='sm'
                as |m|
              >
                <m.Header>Third Modal</m.Header>
                <m.Body>
                  <p class='mb-4'>This is the third and final modal in this
                    example.</p>
                  <p class='text-sm text-neutral-medium'>Each modal maintains its
                    own focus trap and can be closed independently.</p>
                </m.Body>
                <m.Footer @class='flex gap-2'>
                  <Button @onPress={{this.toggleThird}}>
                    Close This
                  </Button>
                  <Button @intent='danger' @onPress={{this.closeAll}}>
                    Close All
                  </Button>
                </m.Footer>
              </Modal>

            </m.Body>
            <m.Footer @class='flex gap-2'>
              <Button @onPress={{this.toggleSecond}}>
                Close
              </Button>
              <Button @intent='primary' @onPress={{this.toggleThird}}>
                Open Third Modal
              </Button>
            </m.Footer>
          </Modal>

        </m.Body>
        <m.Footer @class='flex gap-2'>
          <Button @onPress={{this.toggleFirst}}>
            Close
          </Button>
          <Button @intent='primary' @onPress={{this.toggleSecond}}>
            Open Second Modal
          </Button>
        </m.Footer>
      </Modal>

    </div>
  </template>
}

```

--------------------------------

### Run Frontile Test App

Source: https://github.com/josemarluedke/frontile/blob/main/README.md

Command to start the development server for the Frontile test application using pnpm.

```sh
pnpm start
```

--------------------------------

### Remove Old Packages and Install Consolidated Package

Source: https://github.com/josemarluedke/frontile/blob/main/docs/migrations/v0.18/package-consolidation.md

Use these commands to uninstall the old @frontile/* packages and install the new 'frontile' package. This applies to npm, pnpm, and yarn.

```bash
# Remove old packages
npm uninstall @frontile/buttons @frontile/collections @frontile/forms \
  @frontile/overlays @frontile/notifications @frontile/status @frontile/utilities

# Install the consolidated package (if not already installed)
npm install frontile @frontile/theme
```

```bash
# pnpm
pnpm remove @frontile/buttons @frontile/collections @frontile/forms \
  @frontile/overlays @frontile/notifications @frontile/status @frontile/utilities
pnpm add frontile @frontile/theme

# yarn
yarn remove @frontile/buttons @frontile/collections @frontile/forms \
  @frontile/overlays @frontile/notifications @frontile/status @frontile/utilities
yarn add frontile @frontile/theme
```

--------------------------------

### Border Width Examples

Source: https://github.com/josemarluedke/frontile/blob/main/docs/theming/design-tokens/borders.md

Provides practical examples of using border width tokens in common UI components. Includes a subtle card with a thin border, a standard input field with a default border, and a selected item with a heavy border.

```gts
<template>
  <div class='space-y-4'>
    {{! Subtle card }}
    <div class='border-thin border-neutral-medium rounded p-4'>
      <h3 class='text-header-sm mb-2'>Subtle Card</h3>
      <p class='text-body-sm text-neutral-strong'>Uses thin border for minimal visual weight</p>
    </div>

    {{! Standard input }}
    <input
      type='text'
      placeholder='Standard input field'
      class='w-full border border-neutral-medium rounded px-4 py-2 focus:outline-none focus:ring-2 focus:ring-primary-medium'
    />

    {{! Selected item with heavy border }}
    <div class='border-heavy border-primary-medium rounded p-4 bg-primary-subtle'>
      <h3 class='text-header-sm mb-2 text-primary-strong'>Selected Item</h3>
      <p class='text-body-sm text-primary-strong'>Uses heavy border to show selection</p>
    </div>
  </div>
</template>
```

--------------------------------

### ProgressBar with Description

Source: https://github.com/josemarluedke/frontile/blob/main/packages/frontile/src/components/status/progress-bar.md

Example of using the ProgressBar with both a label and a description to provide more context.

```gjs
import { ProgressBar } from 'frontile';

<template>
  <ProgressBar
    @progress={{50}}
    @label='Uploading'
    @description='Estimated time left'
  />
</template>
```

--------------------------------

### Initialize Frontile Tests

Source: https://github.com/josemarluedke/frontile/blob/main/site/tests/index.html

Imports necessary testing modules and starts the test runner. Ensure all test files are discoverable by the module loader.

```javascript
import "ember-testing";
import { start } from "./test-helper";
import.meta.glob("./**/*.{js,ts,gjs,gts}", { eager: true });
start();
```

--------------------------------

### Basic ProgressBar Usage

Source: https://github.com/josemarluedke/frontile/blob/main/packages/frontile/src/components/status/progress-bar.md

A simple example of how to use the ProgressBar component with a progress value and a label.

```gjs
import { ProgressBar } from 'frontile';

<template><ProgressBar @progress={{50}} @label='Progress' /></template>
```

--------------------------------

### Update Custom Theme Configuration (v0.17)

Source: https://github.com/josemarluedke/frontile/blob/main/docs/migrations/v0.18/theme-configuration.md

Example of a custom Frontile theme configuration file structure before v0.18.

```javascript
const { frontile } = require('@frontile/theme/plugin');

module.exports = frontile({
  hoverOpacity: 0.9,
  disabledOpacity: 0.4,
  // other flat properties
});
```

--------------------------------

### Setting Up Global Styles

Source: https://github.com/josemarluedke/frontile/blob/main/docs/theming/component-styles.md

Create a theme file (e.g., `app/theme.js`) to define global style customizations for Frontile components.

```javascript
// app/theme.js
import { useStyles, registerCustomStyles, tv } from '@frontile/theme';

const components = useStyles();

registerCustomStyles({
  // stuff ...
});
```

```javascript
// app/app.js
import Application from '@ember/application';
// stuff...
import './theme'; // Import your theme file here

export default class App extends Application {
  // stuff...
}

loadInitializers(App, config.modulePrefix);
```

--------------------------------

### Displaying All Icon Sizes

Source: https://github.com/josemarluedke/frontile/blob/main/docs/theming/design-tokens/icons.md

This example demonstrates how to use various icon size utility classes to display different icon sizes. It imports an icon component and applies size classes like `size-icon-pico` and `size-icon-mega` to visually represent each size. Use this to see all available icon sizes in action.

```gts
import { CheckIcon } from 'site/components/icons';

<template>
  <div class='grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4'>
    <div class='flex items-center gap-3 p-3 border border-neutral-medium rounded'>
      <CheckIcon class='size-icon-pico text-primary-medium' />
      <div>
        <div class='font-medium'>Pico</div>
        <code class='text-xs'>size-icon-pico</code>
      </div>
    </div>
    <div class='flex items-center gap-3 p-3 border border-neutral-medium rounded'>
      <CheckIcon class='size-icon-nano text-primary-medium' />
      <div>
        <div class='font-medium'>Nano</div>
        <code class='text-xs'>size-icon-nano</code>
      </div>
    </div>
    <div class='flex items-center gap-3 p-3 border border-neutral-medium rounded'>
      <CheckIcon class='size-icon-micro text-primary-medium' />
      <div>
        <div class='font-medium'>Micro</div>
        <code class='text-xs'>size-icon-micro</code>
      </div>
    </div>
    <div class='flex items-center gap-3 p-3 border border-neutral-medium rounded'>
      <CheckIcon class='size-icon-3xs text-primary-medium' />
      <div>
        <div class='font-medium'>3XS</div>
        <code class='text-xs'>size-icon-3xs</code>
      </div>
    </div>
    <div class='flex items-center gap-3 p-3 border border-neutral-medium rounded'>
      <CheckIcon class='size-icon-2xs text-primary-medium' />
      <div>
        <div class='font-medium'>2XS</div>
        <code class='text-xs'>size-icon-2xs</code>
      </div>
    </div>
    <div class='flex items-center gap-3 p-3 border border-neutral-medium rounded'>
      <CheckIcon class='size-icon-xs text-primary-medium' />
      <div>
        <div class='font-medium'>XS</div>
        <code class='text-xs'>size-icon-xs</code>
      </div>
    </div>
    <div class='flex items-center gap-3 p-3 border border-neutral-medium rounded'>
      <CheckIcon class='size-icon-sm text-primary-medium' />
      <div>
        <div class='font-medium'>SM</div>
        <code class='text-xs'>size-icon-sm</code>
      </div>
    </div>
    <div class='flex items-center gap-3 p-3 border border-neutral-medium rounded'>
      <CheckIcon class='size-icon-md text-primary-medium' />
      <div>
        <div class='font-medium'>MD</div>
        <code class='text-xs'>size-icon-md</code>
      </div>
    </div>
    <div class='flex items-center gap-3 p-3 border border-neutral-medium rounded'>
      <CheckIcon class='size-icon-lg text-primary-medium' />
      <div>
        <div class='font-medium'>LG</div>
        <code class='text-xs'>size-icon-lg</code>
      </div>
    </div>
    <div class='flex items-center gap-3 p-3 border border-neutral-medium rounded'>
      <CheckIcon class='size-icon-xl text-primary-medium' />
      <div>
        <div class='font-medium'>XL</div>
        <code class='text-xs'>size-icon-xl</code>
      </div>
    </div>
    <div class='flex items-center gap-3 p-3 border border-neutral-medium rounded'>
      <CheckIcon class='size-icon-2xl text-primary-medium' />
      <div>
        <div class='font-medium'>2XL</div>
        <code class='text-xs'>size-icon-2xl</code>
      </div>
    </div>
    <div class='flex items-center gap-3 p-3 border border-neutral-medium rounded'>
      <CheckIcon class='size-icon-3xl text-primary-medium' />
      <div>
        <div class='font-medium'>3XL</div>
        <code class='text-xs'>size-icon-3xl</code>
      </div>
    </div>
    <div class='flex items-center gap-3 p-3 border border-neutral-medium rounded'>
      <CheckIcon class='size-icon-kilo text-primary-medium' />
      <div>
        <div class='font-medium'>Kilo</div>
        <code class='text-xs'>size-icon-kilo</code>
      </div>
    </div>
    <div class='flex items-center gap-3 p-3 border border-neutral-medium rounded'>
      <CheckIcon class='size-icon-mega text-primary-medium' />
      <div>
        <div class='font-medium'>Mega</div>
        <code class='text-xs'>size-icon-mega</code>
      </div>
    </div>
  </div>
</template>
```

--------------------------------

### Install Frontile Component Library

Source: https://github.com/josemarluedke/frontile/blob/main/packages/frontile/README.md

Use the Ember CLI to install the frontile addon into your Ember Octane application.

```sh
ember install frontile
```

--------------------------------

### Template-Only Component Example

Source: https://github.com/josemarluedke/frontile/blob/main/AGENTS.md

Example of a template-only component using TypeScript and the TOC helper. Ensure to import 'TOC' from '@ember/component/template-only'.

```typescript
import type { TOC } from '@ember/component/template-only';

export interface Signature {
  Args: {
    title: string;
  };
}

const MyComponent: TOC<Signature> = <template>
  <div>{{@title}}</div>
</template>;

export default MyComponent;
```

--------------------------------

### Navigate to Project Directory

Source: https://github.com/josemarluedke/frontile/blob/main/test-app/README.md

Change the current directory to the cloned test-app folder.

```bash
cd test-app
```

--------------------------------

### Checkbox Group Data Management Example

Source: https://github.com/josemarluedke/frontile/blob/main/docs/migrations/forms-legacy.md

Example of how to manage selected values for CheckboxGroup, which remains the same pattern as the legacy component.

```js
// Tracking selected values (same pattern as before)
@tracked selectedInterests = [];

isInterestSelected(value) {
  return this.selectedInterests.includes(value);
}

setInterests = (value, isChecked) => {
  if (isChecked) {
    this.selectedInterests = [...this.selectedInterests, value];
  } else {
    this.selectedInterests = this.selectedInterests.filter(v => v !== value);
  }
};
```

--------------------------------

### Create a Themed Button

Source: https://github.com/josemarluedke/frontile/blob/main/docs/theming/overview.md

This example shows how to create a button that automatically adapts to light and dark themes using Frontile's color utilities. The `on-primary-medium` class ensures optimal text contrast for accessibility.

```gts
<template>
  <button
    class='bg-primary-medium text-on-primary-medium hover:bg-primary-soft px-4 py-2 rounded'
  >
    Click me
  </button>
</template>
```

--------------------------------

### Build for Production

Source: https://github.com/josemarluedke/frontile/blob/main/test-app/README.md

Build the application for production deployment.

```bash
npm run build
```

--------------------------------

### Notification Placement Example

Source: https://github.com/josemarluedke/frontile/blob/main/packages/frontile/docs/notifications-usage.md

Control where notifications appear on screen using the `@placement` argument. This example demonstrates setting the placement via radio buttons.

```gts
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { service } from '@ember/service';
import { Button } from 'frontile';
import { RadioGroup } from 'frontile';
import {
  NotificationsContainer,
  type NotificationsService
} from 'frontile';

export default class PositionExample extends Component {
  @service notifications!: NotificationsService;
  @tracked placement = 'bottom-right';

  placements = [
    { key: 'top-left', label: 'Top Left' },
    { key: 'top-center', label: 'Top Center' },
    { key: 'top-right', label: 'Top Right' },
    { key: 'bottom-left', label: 'Bottom Left' },
    { key: 'bottom-center', label: 'Bottom Center' },
    { key: 'bottom-right', label: 'Bottom Right' }
  ];

  setPlacement = (placement: string) => {
    this.placement = placement;
  };

  showNotification = () => {
    this.notifications.add(`Positioned at ${this.placement}`, {
      appearance: 'info'
    });
  };

  <template>
    <div class='flex flex-col gap-4'>
      <RadioGroup
        @label='Position'
        @value={{this.placement}}
        @onChange={{this.setPlacement}}
        as |Radio|
      >
        {{#each this.placements as |option|}}
          <Radio @value={{option.key}} @label={{option.label}} />
        {{/each}}
      </RadioGroup>

      <Button @onPress={{this.showNotification}}>
        Show at
        {{this.placement}}
      </Button>

      <NotificationsContainer @placement={{this.placement}} />
    </div>
  </template>
}
```

--------------------------------

### Input with Start and End Content

Source: https://github.com/josemarluedke/frontile/blob/main/packages/frontile/src/components/forms/input.md

Shows how to add custom content, such as currency symbols or buttons, at the start and end of the input field using named blocks.

```gts
import Component from '@glimmer/component';
import { Input } from 'frontile';
import { SearchIcon } from 'site/components/icons';

export default class InputWithContent extends Component {
  <template>
    <div class='flex flex-col gap-4'>
      <Input @label='Price'>
        <:startContent>
          <span class='text-neutral-soft'>$</span>
        </:startContent>
        <:endContent>
          <span class='text-neutral-soft'>USD</span>
        </:endContent>
      </Input>

      <Input @label='Search'>
        <:startContent>
          <SearchIcon />
        </:startContent>
        <:endContent>
          <button type='button'>Go</button>
        </:endContent>
      </Input>
    </div>
  </template>
}
```

--------------------------------

### Comprehensive Form Example with All Component Types

Source: https://github.com/josemarluedke/frontile/blob/main/packages/frontile/src/components/forms/form.md

Demonstrates the usage of the Form component with a wide array of Frontile's form elements, including Input, Textarea, NativeSelect, Select, RadioGroup, CheckboxGroup, and Checkbox. It also shows how to handle form changes and submissions, and display the form data.

```gts
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import {
  Form,
  Input,
  Textarea,
  Checkbox,
  CheckboxGroup,
  RadioGroup,
  NativeSelect,
  Select,
  type FormResultData
} from 'frontile';
import { Button } from 'frontile';

export default class ComprehensiveForm extends Component {
  @tracked formData: FormResultData = {};
  @tracked lastEventType = '';
  @tracked selectedSkillLevel: string | null = null;

  countries = [
    'United States',
    'Canada',
    'United Kingdom',
    'Australia',
    'Germany'
  ];

  skillLevels = [
    { label: 'Beginner (0-1 years)', key: 'beginner' },
    { label: 'Intermediate (2-5 years)', key: 'intermediate' },
    { label: 'Advanced (5+ years)', key: 'advanced' },
    { label: 'Expert (10+ years)', key: 'expert' }
  ];

  handleFormChange = (data: FormResultData, event: Event) => {
    this.formData = data;
    this.lastEventType = 'input';
    console.log('Form input:', { data, event });
  };

  handleFormSubmit = (data: FormResultData, event: SubmitEvent) => {
    this.formData = data;
    this.lastEventType = 'submit';
    console.log('Form submit:', { data, event });
  };

  handleSkillLevelChange = (selectedKey: string | null) => {
    this.selectedSkillLevel = selectedKey;
  };

  <template>
    <div class='flex flex-col gap-4'>
      <Form
        @onChange={{this.handleFormChange}}
        @onSubmit={{this.handleFormSubmit}}
      >
        <div class='flex flex-col gap-4'>

          <div class='grid grid-cols-1 md:grid-cols-2 gap-4'>
            <Input @name='firstName' @label='First Name' />
            <Input @name='lastName' @label='Last Name' />
          </div>

          <Input @name='email' @label='Email Address' @type='email' />

          <Textarea
            @name='bio'
            @label='Biography'
            @description='Tell us about yourself'
            rows='4'
          />

          <NativeSelect
            @name='country'
            @label='Country'
            @items={{this.countries}}
            @placeholder='Select a country'
          />

          <Select
            @name='skillLevel'
            @label='Skill Level'
            @items={{this.skillLevels}}
            @placeholder='Select your skill level'
            @selectedKey={{this.selectedSkillLevel}}
            @onSelectionChange={{this.handleSkillLevelChange}}
          />

          <RadioGroup @name='experience' @label='Experience Level' as |Radio|>
            <Radio @label='Beginner' @value='beginner' />
            <Radio @label='Intermediate' @value='intermediate' />
            <Radio @label='Advanced' @value='advanced' />
          </RadioGroup>

          <CheckboxGroup
            @name='interests'
            @label='Areas of Interest'
            as |Checkbox|
          >
            <Checkbox @name='frontend' @label='Frontend Development' />
            <Checkbox @name='backend' @label='Backend Development' />
            <Checkbox @name='mobile' @label='Mobile Development' />
            <Checkbox @name='design' @label='UI/UX Design' />
          </CheckboxGroup>

          <div class='flex items-center gap-4'>
            <Checkbox @name='subscribe' @label='Subscribe to newsletter' />
            <Checkbox
              @name='terms'
              @label='I agree to the terms and conditions'
            />
          </div>

          <Button type='submit'>
            Submit Application
          </Button>
        </div>
      </Form>

      <div class='p-4 bg-neutral-subtle rounded'>
        <div class='flex justify-between items-center mb-2'>
          <h4 class='font-medium'>Form Data</h4>
          <span class='text-sm text-neutral-medium'>
            Last event:
            <strong>{{this.lastEventType}}</strong>
          </span>
        </div>
        <pre class='text-sm overflow-auto max-h-64'>{{JSON.stringify
            this.formData
            null
            2
          }}</pre>
      </div>
    </div>
  </template>
}

```

--------------------------------

### Notification Custom Actions Example

Source: https://github.com/josemarluedke/frontile/blob/main/packages/frontile/docs/notifications-usage.md

Add action buttons to notifications for user interaction. This example shows how to include 'View' and 'Share' actions, or an 'Undo' action.

```gts
import Component from '@glimmer/component';
import { service } from '@ember/service';
import { tracked } from '@glimmer/tracking';
import { Button } from 'frontile';
import type { NotificationsService } from 'frontile';

export default class ActionsExample extends Component {
  @service notifications!: NotificationsService;
  @tracked result = '';

  showWithActions = () => {
    this.result = '';
    this.notifications.add('File uploaded successfully!', {
      appearance: 'success',
      duration: 10000, // Keep it open longer for user to act
      customActions: [
        {
          label: 'View',
          onClick: () => {
            this.result = 'User clicked View';
          }
        },
        {
          label: 'Share',
          onClick: () => {
            this.result = 'User clicked Share';
          }
        }
      ]
    });
  };

  showUndoAction = () => {
    this.result = '';
    this.notifications.add('Item deleted', {
      appearance: 'info',
      duration: 8000,
      customActions: [
        {
          label: 'Undo',
          onClick: () => {
            this.result = 'Undo clicked - item restored!';
          }
        }
      ]
    });
  };

  <template>
    <div class='flex flex-col gap-4'>
      <div class='flex gap-2'>
        <Button @onPress={{this.showWithActions}}>
          Upload Success with Actions
        </Button>
        <Button @onPress={{this.showUndoAction}}>
          Show Undo Action
        </Button>
      </div>

      {{#if this.result}}
        <div class='p-3 rounded border bg-success-50 text-success-medium'>
          {{this.result}}
        </div>
      {{/if}}
    </div>
  </template>
}
```

--------------------------------

### Build Application

Source: https://github.com/josemarluedke/frontile/blob/main/site/README.md

Build the application for development or production environments.

```bash
pnpm ember build
```

```bash
pnpm build
```

--------------------------------

### Configure Custom Theme

Source: https://github.com/josemarluedke/frontile/blob/main/docs/theming/overview.md

Create a frontile.js file in your project root for custom theme configuration.

```javascript
const { frontile } = require('@frontile/theme/plugin');

module.exports = frontile({
  /* your configuration */
});
```

--------------------------------

### Avoiding Hard-Coded Colors

Source: https://github.com/josemarluedke/frontile/blob/main/docs/theming/configuration/theme-switching.md

Avoid using hard-coded Tailwind colors that do not adapt to themes. The 'Good' example uses semantic colors that adapt automatically, while the 'Bad' example uses fixed colors.

```html
<!-- ✗ Bad - doesn't adapt to theme -->
<div class="bg-gray-900 text-white">
  Content
</div>

<!-- ✓ Good - adapts automatically -->
<div class="bg-surface-canvas text-neutral-strong">
  Content
</div>
```

--------------------------------

### Initially Open Collapsible Panel

Source: https://github.com/josemarluedke/frontile/blob/main/packages/frontile/src/components/utilities/collapsible.md

Shows how to initialize a Collapsible panel in an open state using the @isOpen attribute. This is useful for welcome messages or important information that should be visible by default.

```gts
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { action } from '@ember/object';
import { Collapsible, Button } from 'frontile';

export default class InitiallyOpen extends Component {
  @tracked isOpen = true;

  @action toggle() {
    this.isOpen = !this.isOpen;
  }

  <template>
    <div class='max-w-md'>
      <div class='border border-primary-soft rounded-lg overflow-hidden'>
        <div class='p-4 bg-primary-subtle border-b border-primary-soft'>
          <h3 class='font-semibold'>Welcome Message</h3>
        </div>

        <Collapsible @isOpen={{this.isOpen}}>
          <div class='p-4'>
            <p class='text-neutral-medium mb-4'>
              Thank you for signing up! Here are some quick tips to get started
              with our platform.
            </p>
            <ul class='space-y-2 text-neutral-medium'>
              <li>→ Complete your profile</li>
              <li>→ Connect your accounts</li>
              <li>→ Explore the dashboard</li>
            </ul>
          </div>
        </Collapsible>

        <div class='px-4 py-3 bg-neutral-subtle border-t border-neutral-subtle'>
          <Button @size='sm' @appearance='minimal' @onPress={{this.toggle}}>
            {{if this.isOpen 'Dismiss' 'Show Again'}}
          </Button>
        </div>
      </div>
    </div>
  </template>
}

```

--------------------------------

### Good vs. Bad Base Backgrounds

Source: https://github.com/josemarluedke/frontile/blob/main/docs/theming/configuration/theme-switching.md

Always provide a solid base background for surface overlay colors to ensure visibility. The 'Good' example includes a base background, while the 'Bad' example lacks one.

```html
<!-- ✓ Good - has base background -->
<div class="theme-inverse bg-surface-canvas">
  <div class="bg-surface-overlay-subtle p-4">
    Content
  </div>
</div>

<!-- ✗ Bad - overlay has no base -->
<div class="theme-inverse">
  <div class="bg-surface-overlay-subtle p-4">
    Content (might be invisible!)
  </div>
</div>
```

--------------------------------

### Run All Tests

Source: https://github.com/josemarluedke/frontile/blob/main/AGENTS.md

Execute all tests for the project. Navigate to the 'test-app' directory first.

```bash
cd test-app && pnpm ember test
```

--------------------------------

### Build Documentation Site

Source: https://github.com/josemarluedke/frontile/blob/main/CLAUDE.md

Builds the static assets for the documentation site. Use this to confirm rendered demos after doc/style changes.

```bash
cd site && pnpm build
```

--------------------------------

### Frontile Input and Link Focus Example

Source: https://github.com/josemarluedke/frontile/blob/main/docs/accessibility/focus-management.md

Demonstrates how Frontile's focus management applies to both input fields and anchor tags. Observe the difference in focus indicator visibility when navigating with the Tab key versus using the mouse.

```gts
import { Input } from 'frontile';

<template>
  <div class='space-y-4'>
    <Input @placeholder='Focus me with Tab or mouse' />

    <a
      class='inline-block px-4 py-2 bg-primary-soft text-white rounded hover:bg-primary-medium focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-soft focus-visible:ring-offset-2'
      href='javascript:void(0)'
    >
      Focus me with Tab or mouse
    </a>
  </div>
</template>
```

--------------------------------

### Persistent Notifications Example

Source: https://github.com/josemarluedke/frontile/blob/main/packages/frontile/docs/notifications-usage.md

Use `preserve: true` to prevent automatic dismissal of notifications. This example also shows how to create a notification without a close button, requiring user interaction with custom actions to dismiss.

```gts
import Component from '@glimmer/component';
import { service } from '@ember/service';
import { Button } from 'frontile';
import type { NotificationsService } from 'frontile';

export default class PersistentExample extends Component {
  @service notifications!: NotificationsService;

  showPersistent = () => {
    this.notifications.add('This notification stays until manually closed', {
      appearance: 'warning',
      preserve: true
    });
  };

  showWithoutCloseButton = () => {
    this.notifications.add('No close button - click actions to dismiss', {
      appearance: 'info',
      preserve: true,
      allowClosing: false,
      customActions: [
        {
          label: 'Got it',
          onClick: () => {
            // This will dismiss the notification
          }
        }
      ]
    });
  };

  <template>
    <div class='flex gap-2'>
      <Button @onPress={{this.showPersistent}}>
        Persistent Notification
      </Button>
      <Button @onPress={{this.showWithoutCloseButton}}>
        No Close Button
      </Button>
    </div>
  </template>
}
```

--------------------------------

### Migrate from Scoped Packages

Source: https://github.com/josemarluedke/frontile/blob/main/docs/installation.md

Example demonstrating how to update imports when migrating from older scoped packages like '@frontile/buttons' to the consolidated 'frontile' package.

```diff
-
import { Button } from '@frontile/buttons';
+
import { Button } from 'frontile';
```

--------------------------------

### Overlay Component: Render In Place Example

Source: https://github.com/josemarluedke/frontile/blob/main/packages/frontile/src/components/overlays/overlay.md

Demonstrates how to use the Overlay component with the `renderInPlace` option set to true. This renders the overlay content directly within its parent container instead of using a portal. The example also shows the default portal rendering behavior for comparison.

```gts
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { action } from '@ember/object';
import { Overlay } from 'frontile';
import { Button } from 'frontile';

export default class RenderInPlace extends Component {
  @tracked portalOpen = false;
  @tracked inPlaceOpen = false;

  @action togglePortal() {
    this.portalOpen = !this.portalOpen;
  }

  @action toggleInPlace() {
    this.inPlaceOpen = !this.inPlaceOpen;
  }

  <template>
    <div class='flex flex-col gap-4'>
      <div class='flex gap-2'>
        <Button @onPress={{this.togglePortal}}>
          Portal Overlay (Default)
        </Button>
        <Button @onPress={{this.toggleInPlace}}>
          In-Place Overlay
        </Button>
      </div>

      <div
        class='relative border-2 border-dashed border-neutral-soft p-4 min-h-48'
      >
        <p class='text-sm text-neutral-medium mb-4'>This container shows the
          difference between portal and in-place rendering.</p>

        <Overlay
          @isOpen={{this.inPlaceOpen}}
          @onClose={{this.toggleInPlace}}
          @renderInPlace={{true}}
        >
          <div
            class='absolute inset-4 bg-content1 p-4 rounded shadow-lg border'
          >
            <h3 class='font-semibold mb-2'>In-Place Overlay</h3>
            <p class='text-sm mb-4'>This overlay is rendered within its parent
              container.</p>
            <Button @size='sm' @onPress={{this.toggleInPlace}}>Close</Button>
          </div>
        </Overlay>
      </div>

      <Overlay @isOpen={{this.portalOpen}} @onClose={{this.togglePortal}}>
        <div class='bg-content1 p-6 rounded-lg shadow-lg'>
          <h3 class='font-semibold mb-2'>Portal Overlay</h3>
          <p class='mb-4'>This overlay is rendered in a portal (outside the
            normal DOM tree).</p>
          <Button @onPress={{this.togglePortal}}>Close</Button>
        </div>
      </Overlay>
    </div>
  </template>
}

```

--------------------------------

### Configure Custom Frontile Theme

Source: https://github.com/josemarluedke/frontile/blob/main/docs/installation.md

Create a `frontile.js` file in your project root to configure custom theme settings. This example shows the basic structure using the `frontile` plugin.

```js
const { frontile } = require('@frontile/theme/plugin');

module.exports = frontile({
  /* your config */
});
```