### Download CivicTheme GovCMS Setup Script

Source: https://github.com/civictheme/docs/blob/main/installation/govcms-saas-automated.md

Downloads the automated CivicTheme GovCMS setup script from GitHub and makes it executable. This script automates the installation and configuration of CivicTheme and a subtheme within a GovCMS project.

```bash
curl -o setup_civictheme.sh \
https://raw.githubusercontent.com/civictheme/civictheme_govcms/refs/heads/main/scripts/setup_civictheme.sh \
&& chmod +x setup_civictheme.sh
```

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

### Run CivicTheme GovCMS Setup Script

Source: https://github.com/civictheme/docs/blob/main/installation/govcms-saas-automated.md

Executes the downloaded CivicTheme GovCMS setup script. Requires arguments for CivicTheme version, GovCMS module reference, subtheme machine name, human-readable name, and description. Optional flags control content provisioning.

```bash
./setup_civictheme.sh -c <civictheme_version> \
-g <govcms_module_ref> \
-m <subtheme_machine_name> \
-u "<subtheme_human_name>" \
-d "<subtheme_description>" \
[-p] \
[-n]
```

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

### Generate a Sub-theme using CivicTheme Script (PHP)

Source: https://github.com/civictheme/docs/blob/main/installation/govcms-saas-manual.md

This command uses the `civictheme_create_subtheme.php` script to generate a new sub-theme. It takes machine name, human name, and description as arguments, and optionally removes example overrides. The generated sub-theme is placed in the specified output directory.

```sh
# Generate sub-theme (example overrides are removed using --remove-examples flag). 
# See php civictheme_create_subtheme.php --help
cd web/themes/custom/civictheme
php civictheme_create_subtheme.php <SUBTHEME_MACHINE_NAME> "<SUBTHEME HUMAN NAME>" "<SUBTHEME HUMAN DESCRIPTION>" ../<SUBTHEME_MACHINE_NAME> --remove-examples
```

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

### Install CivicTheme with Content Provisioning

Source: https://github.com/civictheme/docs/blob/main/installation/govcms-saas-automated.md

This command installs CivicTheme with default content provisioning enabled. It requires specifying the CivicTheme version, a GovCMS module reference, and details for the new subtheme.

```bash
./setup_civictheme.sh -c "{{ CIVICTHEME VERSION - see project page }}" \
                      -g "main" \
                      -m "my_gov_project_theme" \
                      -u "My Gov Project Theme" \
                      -d "Custom theme for the My Gov Project website on GovCMS."
```

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

### Install and Configure CivicTheme GovCMS Helper Module (Drush)

Source: https://github.com/civictheme/docs/blob/main/installation/govcms-saas-manual.md

This script installs the `civictheme_govcms` module to remove unnecessary GovCMS configurations, runs Drush commands to enable and then uninstall the module, and exports the updated configuration. It involves creating directories, downloading the module, and executing Drush commands for configuration management.

```sh
# If `web/modules/contrib` is not writable, you can use an alternative directory `web/themes/custom/civictheme` etc.
mkdir -p /app/web/themes/custom/civictheme/modules
cd /app/web/themes/custom/civictheme/modules

# Download and extract the helper module.
# Ensure to use the latest tag (not Release) https://github.com/civictheme/civictheme_govcms/tags
wget https://github.com/civictheme/civictheme_govcms/archive/refs/tags/<latest-tag>.tar.gz && tar -xvf <latest-tag>.tar.gz && rm <latest-tag>.tar.gz && mv civictheme_govcms-<latest-tag> civictheme_govcms


# Enable module, run the command to remove entities and uninstall a module.
drush cr
drush pm-enable -y civictheme_govcms
drush civictheme_govcms:remove-config --preserve=user_roles
drush pm-uninstall -y civictheme_govcms

# Delete the module
rm -Rf civictheme_govcms
```

```sh
ahoy drush cex -y
```

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

### Start Development Server with npm

Source: https://github.com/civictheme/docs/blob/main/contributing/contribution-basics.md

View your changes in real-time during development by running the development server. This command is essential for local testing and iteration.

```bash
npm run dev
```

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

### Install CivicTheme Skipping Content Provisioning

Source: https://github.com/civictheme/docs/blob/main/installation/govcms-saas-automated.md

This command installs CivicTheme while skipping the automatic content provisioning step, which is useful for manual control over content blocks. It requires the same arguments as a standard installation, plus the -n flag.

```bash
./setup_civictheme.sh -c "{{ CIVICTHEME VERSION - see project page }}" \
                      -g "main" \
                      -m "my_gov_project_theme" \
                      -u "My Gov Project Theme" \
                      -d "Custom theme for the My Gov Project website on GovCMS." \
                      -n
```

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

### Build Front-End Assets with npm

Source: https://github.com/civictheme/docs/blob/main/installation/govcms-saas-automated.md

These commands are used after installation to build the front-end assets for a CivicTheme subtheme. It involves navigating to the theme directory, setting up Node.js version, installing dependencies, and running the build script.

```bash
cd themes/<SUBTHEME_MACHINE_NAME>
nvm use
npm install
npm run build
```

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

### Install CivicTheme using Composer

Source: https://github.com/civictheme/docs/blob/main/installation/drupal-theme.md

Installs the CivicTheme package for Drupal using Composer. This is the recommended method for managing Drupal theme dependencies.

```sh
composer require drupal/civictheme
```

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

### Key Git and npm Commands for Contribution

Source: https://github.com/civictheme/docs/blob/main/contributing/contribution-basics.md

A summary of essential commands for cloning, installing dependencies, branching, running the dev server, testing, committing, pushing, and updating your branch.

```bash
git clone https://github.com/your-username/civictheme.git
npm install
git checkout -b feature/your-feature-name
npm run dev
npm test
git add . && git commit -m "commit message"
git push origin feature/your-feature-name
git fetch upstream && git merge upstream/main
```

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

### Enable CivicTheme using Drush

Source: https://github.com/civictheme/docs/blob/main/installation/drupal-theme.md

Enables the CivicTheme theme within a Drupal installation using a Drush command. This can also be done via the Drupal UI.

```sh
drush then civictheme
```

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

### Cleanup Unnecessary Files

Source: https://github.com/civictheme/docs/blob/main/installation/govcms-saas-manual.md

This command sequence removes specific PHP and directory files from the CivicTheme installation. This is a cleanup step performed after deployment or when customizing the theme to remove default or starter kit files.

```sh
# Remove unnecessary files.
rm themes/civictheme/civictheme_create_subtheme.php
rm -Rf themes/civictheme/civictheme_starter_kit
```

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

### HTML Grid Markup Example

Source: https://github.com/civictheme/docs/blob/main/development/uikit/extending-components/grid.md

Demonstrates the structure of CivicTheme's grid system using HTML divs with classes for containers, rows, and columns. It shows different column spans across various breakpoints (extra-small to large) and nested grid examples.

```html
<div class="container">
    <div class="row">
        <div class="col-xs-12 col-l-6">100% extra-small viewport / 50% large viewport</div>
    </div>
    <div class="row">
        <div class="col-xs-6 col-m-4 col-l-3">50% extra-small viewport / 33% medium viewport / 25% large viewport</div>
        <div class="col-xs-6 col-m-4 col-l-3">50% extra-small viewport / 33% medium viewport / 25% large viewport</div>
        <div class="col-xs-6 col-m-4 col-l-3">50% extra-small viewport / 33% medium viewport / 25% large viewport</div>
        <div class="col-xs-6 col-m-4 col-l-3">50% extra-small viewport / 33% medium viewport / 25% large viewport</div>
        <div class="col-xs-6 col-m-4 col-l-3">50% extra-small viewport / 33% medium viewport / 25% large viewport</div>
    </div>
    <div class="row">
        <div class="col-xxs-12 ">100% at all viewports</div>
    </div>
    <div class="row">
        <div class="col-l-6">
            <div class="container">
                <div class="row">
                    <div class="col-l-12">Nested column is set within 50% width parent and so is 50% parent container width</div>
                </div>
            </div>
        </div>
    </div>
</div>

```

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

### Install and Set Sub-theme as Default (Drush)

Source: https://github.com/civictheme/docs/blob/main/installation/govcms-saas-manual.md

These Drush commands enable a newly generated sub-theme and then set it as the default theme for the Drupal site. This replaces the previously active theme with the custom sub-theme.

```sh
# Enable sub-theme.
ahoy drush theme:enable <SUBTHEME_MACHINE_NAME> -y
# Set sub-theme as default.
ahoy drush config-set system.theme default <SUBTHEME_MACHINE_NAME> -y
```

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

### Enable CivicTheme and Set as Default (Drush)

Source: https://github.com/civictheme/docs/blob/main/installation/govcms-saas-manual.md

This sequence of Drush commands enables the CivicTheme, sets it as the default frontend theme, and configures standalone URL behavior for media. It also optionally enables and sets an admin theme.

```bash
# Clear Drupal cache.
ahoy drush cr
# Enable CivicTheme and set as default.
ahoy drush theme:enable civictheme
ahoy drush config-set -y system.theme default civictheme
ahoy drush config-set -y media.settings standalone_url true

# Enable admin theme and set as default (optional).
ahoy drush theme:enable adminimal_theme
ahoy drush config-set -y system.theme admin adminimal_theme
```

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

### Extend CivicTheme Navigation Card with Twig Blocks (Twig)

Source: https://github.com/civictheme/docs/blob/main/development/uikit/extending-components/README.md

This example illustrates a more advanced method of extending CivicTheme components using Twig blocks, as seen in the navigation card example. This approach offers greater control over the component's structure and content.

```twig
{# Example of extending a navigation-card component using blocks #}
{% extends '@civictheme/components/02-molecules/navigation-card/navigation-card.twig' %}

{% block navigation_card_title %}
  My Custom Navigation Title
{% endblock %}

{% block navigation_card_links %}
  <ul>
    <li><a href="#">Custom Link 1</a></li>
    <li><a href="#">Custom Link 2</a></li>
  </ul>
{% endblock %}

```

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

### Example of UI Kit Overrides/Additions for CSS

Source: https://github.com/civictheme/docs/blob/main/development/drupal-theme/assets.md

This SCSS file demonstrates how to override or add styles for UI kit components. The path 'assets/sass/block/_local-tasks.scss' is an example location for Drupal-specific style overrides.

```scss
@import "../civictheme/variables.base";

// Override local task block styles
.local-tasks.tabs ul.tabs li.active {
  border-bottom-color: $color-primary;
}
```

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

### HTML Grid Markup Examples for CivicTheme

Source: https://github.com/civictheme/docs/blob/main/development/uikit/components/grid.md

Demonstrates various ways to structure HTML markup using CivicTheme's grid classes for different column spans and nesting scenarios. These classes define how elements should be displayed across extra-small, small, medium, large, and extra-large viewports.

```html
<div class="container">
    <div class="row">
        <div class="col-xs-12 col-l-6">100% extra-small viewport / 50% large viewport</div>
    </div>
    <div class="row">
        <div class="col-xs-6 col-m-4 col-l-3">50% extra-small viewport / 33% medium viewport / 25% large viewport</div>
        <div class="col-xs-6 col-m-4 col-l-3">50% extra-small viewport / 33% medium viewport / 25% large viewport</div>
        <div class="col-xs-6 col-m-4 col-l-3">50% extra-small viewport / 33% medium viewport / 25% large viewport</div>
        <div class="col-xs-6 col-m-4 col-l-3">50% extra-small viewport / 33% medium viewport / 25% large viewport</div>
        <div class="col-xs-6 col-m-4 col-l-3">50% extra-small viewport / 33% medium viewport / 25% large viewport</div>
    </div>
    <div class="row">
        <div class="col-xxs-12 ">100% at all viewports</div>
    </div>
    <div class="row">
        <div class="col-l-6">
            <div class="container">
                <div class="row">
                    <div class="col-l-12">Nested column is set within 50% width parent and so is 50% parent container width</div>
                </div>
            </div>
        </div>
    </div>
</div>
```

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

### Compile and Serve Assets using npm run dist

Source: https://github.com/civictheme/docs/blob/main/development/drupal-theme/assets.md

This command compiles all site assets (CSS, JS) using the Webpack configuration. The compiled assets are then served from the 'dist' directory. Ensure you have the necessary npm packages installed.

```bash
npm run dist
```

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

### Clear Drupal Caches with Drush

Source: https://github.com/civictheme/docs/blob/main/installation/drupal-theme.md

Clears all caches in a Drupal installation using the Drush command-line tool. This is often necessary after installing or updating modules and themes.

```sh
drush cr
```

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

### Enable CivicTheme Required and Optional Modules

Source: https://github.com/civictheme/docs/blob/main/installation/drupal-theme.md

Enables all required and optional contrib modules for CivicTheme using Drush. This command executes a custom provisioning script within the theme's directory.

```sh
drush ev "require_once dirname(\Drupal::getContainer()->get('theme_handler')->rebuildThemeData()\['civictheme']\->getPathname()) . '/theme-settings.provision.inc'; civictheme_enable_modules();"
```

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

### Example of UI Kit Overrides/Additions for JS

Source: https://github.com/civictheme/docs/blob/main/development/drupal-theme/assets.md

This JavaScript file demonstrates how to add or override JavaScript behaviors for UI kit components. This file would typically be placed within the 'components' directory structure to mirror the UI kit.

```javascript
/**
 * @file
 * Custom JavaScript for the demo button component.
 */

(function ($, Drupal) {

  /**
   * Behavior for the demo button.
   */
  Drupal.behaviors.demoButton = {
    attach: function (context, settings) {
      $('.demo-button', context).once('demoButton').on('click', function () {
        alert('Demo button clicked!');
      });
    }
  };

})(jQuery, Drupal);

```

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

### Export Drupal Configuration

Source: https://github.com/civictheme/docs/blob/main/installation/drupal-theme.md

Exports the current configuration of a Drupal site to YAML files using Drush. This is typically done after making configuration changes or provisioning content.

```sh
ahoy drush cex -y
```

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

### Enable Only CivicTheme Required Modules

Source: https://github.com/civictheme/docs/blob/main/installation/drupal-theme.md

Enables only the required contrib modules for CivicTheme using Drush. This command also utilizes a custom provisioning script.

```sh
drush ev "require_once dirname(\Drupal::getContainer()->get('theme_handler')->rebuildThemeData()\['civictheme']\->getPathname()) . '/theme-settings.provision.inc'; civictheme_enable_modules(FALSE);"
```

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

### Export Configuration using Drush

Source: https://github.com/civictheme/docs/blob/main/installation/govcms-content-provisioning.md

This command exports the current configuration of the Drupal site, typically used after making changes or provisioning content. It's a crucial step for managing theme configuration across environments. Ensure Drush is installed and accessible in your environment.

```sh
ahoy drush cex -y

```

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

### Enable Required Modules for CivicTheme (Drush)

Source: https://github.com/civictheme/docs/blob/main/installation/govcms-saas-manual.md

This command enables modules required by CivicTheme by executing a custom Drush script. It relies on the `theme_handler` service to rebuild theme data and execute a provisioning function from the CivicTheme theme settings.

```sh
ahoy drush ev "require_once dirname(Drupal::getContainer()->get('theme_handler')->rebuildThemeData()['civictheme']->getPathname()) . '/theme-settings.provision.inc'; civictheme_enable_modules();"
```

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

### Override CivicTheme Color Variables (SCSS)

Source: https://github.com/civictheme/docs/blob/main/development/uikit/extending-components/README.md

This example demonstrates how to override the base color variables in CivicTheme to customize the look and feel of components. It requires a SCSS preprocessor to compile the styles.

```scss
// Import base variables first
@import "@civictheme/uikit/variables.base.scss";

// Override specific color variables
$color-primary: #007bff;
$color-secondary: #6c757d;
$color-danger: #dc3545;

// You can also override other variables like:
// $font-family-base: 'Arial', sans-serif;
// $line-height-base: 1.6;

```

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

### CSS Example of Generated Tag Styles

Source: https://github.com/civictheme/docs/blob/main/development/drupal-theme/systems/colors.md

This CSS demonstrates the output of the `ct-component-property` mixin for a tag component in both light and dark themes. It shows how background color, border color, and text color are set using CSS custom properties.

```css
.ct-tag.ct-theme-light.ct-tag--primary {
  background-color: var(--ct-tag-light-primary-background-color);
  border-color: var(--ct-tag-light-primary-border-color);
  color: var(--ct-tag-light-primary-color);
}

.ct-tag.ct-theme-dark.ct-tag--primary {
  background-color: var(--ct-tag-dark-primary-background-color);
  border-color: var(--ct-tag-dark-primary-border-color);
  color: var(--ct-tag-dark-primary-color);
}
```

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

### Clear Drupal Caches (Drush)

Source: https://github.com/civictheme/docs/blob/main/installation/govcms-saas-manual.md

Clears all Drupal caches using the Drush command-line tool. This is a crucial step after making configuration or code changes to ensure the site reflects the latest updates.

```sh
ahoy drush cr
```

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

### Remove 'dist' from .gitignore

Source: https://github.com/civictheme/docs/blob/main/installation/govcms-saas-manual.md

This action modifies the `.gitignore` file to prevent the `dist` directory from being tracked by Git. This is typically done before committing built assets to ensure only source files are committed.

```text
dist
```

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

### Referencing Fonts in SASS

Source: https://github.com/civictheme/docs/blob/main/development/drupal-theme/assets.md

This SCSS example shows how to reference font files located in the 'assets/fonts' directory. This allows you to use custom or extended font sets within your theme.

```scss
@font-face {
  font-family: 'MyCustomFont';
  src: url('../fonts/my-custom-font.woff2') format('woff2'),
       url('../fonts/my-custom-font.woff') format('woff');
  font-weight: normal;
  font-style: normal;
}

body {
  font-family: 'MyCustomFont', sans-serif;
}

```

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

### Extend Twig Components with Twig Blocks

Source: https://github.com/civictheme/docs/blob/main/development/uikit/extending-components.md

This example shows how to extend CivicTheme components using Twig blocks for more advanced customization. Twig blocks allow for overriding or extending specific sections of a component's template.

```twig
{# Example of extending a navigation-card component using Twig blocks #}
{% extends '@civictheme/components/02-molecules/navigation-card/navigation-card.twig' %}

{% block navigation_card_actions %}
  {# Add custom action buttons here #}
  <button class="button">Custom Action</button>
{% endblock %}
```

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

### Extend CivicTheme Components with Twig Slots (Twig)

Source: https://github.com/civictheme/docs/blob/main/development/uikit/extending-components/README.md

This example shows how to extend a CivicTheme component by injecting HTML into pre-defined slots (variables) within the Twig template. This allows for flexible content insertion without modifying the core component structure.

```twig
{# Example of extending a promo-card component #}
{% embed '@civictheme/components/02-molecules/promo-card/promo-card.twig' %}
  {% block content_slot %}
    <h2>Custom Title</h2>
    <p>This content is injected into the main content slot of the promo card.</p>
  {% endblock %}

  {% block image_slot %}
    <img src="/path/to/your/image.jpg" alt="Custom Image">
  {% endblock %}
{% endembed %}

```

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

### Custom Field Processing Logic (PHP)

Source: https://github.com/civictheme/docs/blob/main/development/drupal-theme/systems/mapping.md

This PHP code defines a custom preprocess function to extract and process a specific Drupal field's value. It validates the field name, retrieves the node, and uses a CivicTheme utility to get the field value, adding it to the variables for Twig.

```php
use Drupal\Core\Entity\FieldableEntityInterface;

function _civictheme_preprocess_custom_field(array &$variables): void {
  if ($variables['field_name'] !== 'field_custom_field') {
    return;
  }

  $node = $variables['element']['#object'] ?? NULL;
  if ($node instanceof FieldableEntityInterface) {
    $variables['custom_value'] = civictheme_get_field_value($node, 'field_c_n_custom', TRUE);
  }
}
```

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

### Commit and Push Changes with Git

Source: https://github.com/civictheme/docs/blob/main/contributing/contribution-basics.md

Stage all changes, commit them with a descriptive message, and then push your branch to the remote repository. This prepares your contribution for review.

```bash
git add .
git commit -m "Add new button component with hover state"
git push origin feature/your-feature-name
```

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

### Storybook Configuration (`.stories.js`)

Source: https://github.com/civictheme/docs/blob/main/development/drupal-theme/systems/components.md

Creates interactive documentation and a testing environment for components in Storybook. It maps component props to Storybook controls, provides default values, and enables interactive testing of prop combinations.

```javascript
import { Button } from './Button.twig';
import DrupalAttribute from 'drupal-attribute';

export default {
  title: 'Components/Button',
  component: 'Button',
  argTypes: {
    label: {
      control: 'text',
      description: 'The text displayed on the button.'
    },
    variant: {
      control: {
        type: 'radio',
        options: ['primary', 'secondary', 'tertiary']
      },
      description: 'The button style.'
    },
    size: {
      control: {
        type: 'select',
        options: ['small', 'medium', 'large']
      },
      description: 'The button size.'
    },
    disabled: {
      control: 'boolean',
      description: 'Whether the button is disabled.'
    },
  },
};

const Template = (args) => Button(args);

export const Default = Template.bind({});
Default.args = {
  label: 'Click Me',
  variant: 'primary',
  size: 'medium',
  disabled: false,
};

export const Secondary = Template.bind({});
Secondary.args = {
  label: 'Learn More',
  variant: 'secondary',
  size: 'medium',
  disabled: false,
};
```

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

### Create CivicTheme Sub-theme (PHP)

Source: https://github.com/civictheme/docs/blob/main/development/drupal-theme/sub-theme.md

Generates a new sub-theme based on CivicTheme. Requires theme machine name, human-readable name, description, and the target path. This script sets up the basic structure for a new theme.

```shell
php civictheme_create_subtheme.php <theme_machine_name> "Human theme name" "Human theme description" /path/to/theme_machine_name
```

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

### Fetch and Merge Upstream Changes with Git

Source: https://github.com/civictheme/docs/blob/main/contributing/contribution-basics.md

Keep your local repository in sync with the latest updates from the upstream CivicTheme repository. This helps prevent merge conflicts.

```bash
git fetch upstream
git merge upstream/main
```

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

### Create New Branch with Git

Source: https://github.com/civictheme/docs/blob/main/contributing/contribution-basics.md

Isolate your work by creating a new branch for your feature or fix. This command is fundamental for managing contributions in Git.

```bash
git checkout -b feature/your-feature-name
```

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

### Compile Sub-theme Assets (NPM)

Source: https://github.com/civictheme/docs/blob/main/development/drupal-theme/sub-theme.md

Compiles the front-end assets (like CSS and JavaScript) for the sub-theme using npm. This command assumes you are in the sub-theme's directory and requires Node.js version 18.14 or higher.

```shell
npm run build
```

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

### Component Template (`.twig`)

Source: https://github.com/civictheme/docs/blob/main/development/drupal-theme/systems/components.md

Defines the HTML structure and rendering logic for a component using Twig. It includes comprehensive documentation, prop validation, conditional logic, CSS class generation using BEM, and accessibility attributes.

```twig
{#
  Button Component

  Purpose: Renders a reusable button.

  Props:
    label (string): The text displayed on the button. (default: "Click Me")
    variant (string): The button style (primary, secondary, tertiary). (default: "primary")
    size (string): The button size (small, medium, large). (default: "medium")
    disabled (boolean): Whether the button is disabled. (default: false)
#}
{% set button_classes = [
  'civic-button',
  'civic-button--' ~ variant,
  'civic-button--' ~ size
] %}
<button class="{{ button_classes | join(' ') }}" {% if disabled %}disabled{% endif %}>
  {{ label }}
</button>
```

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

### Inline Code Formatting Convention

Source: https://github.com/civictheme/docs/blob/main/development/maintenance/authoring-documentation/README.md

This convention specifies the use of inline code formatting for specific values within the documentation. It helps to visually distinguish these values from regular text, improving readability and clarity.

```markdown
Use inline code for values: `Light`, `Dark`, `Top`, `Both`, `Expanded`
```

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

### Enable Sub-theme (Drush)

Source: https://github.com/civictheme/docs/blob/main/development/drupal-theme/sub-theme.md

Enables a previously created theme using the Drush command-line tool. This command is used to activate the theme within the Drupal environment.

```shell
drush theme:enable theme_machine_name
```

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

### Local Site Build Command (Ahoy)

Source: https://github.com/civictheme/docs/blob/main/development/drupal-theme/updating-civitheme-govcms-sass.md

This command, 'ahoy build', is used to re-provision the local development environment. It ensures that the updated configuration and theme changes are applied to the local site, allowing for thorough testing before deployment.

```sh
ahoy build
```

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

### SCSS Breakpoint Mixin Usage

Source: https://github.com/civictheme/docs/blob/main/development/uikit/extending-components/grid.md

Illustrates how to use the `ct-breakpoint()` mixin in SCSS to apply styles conditionally based on predefined breakpoints. It shows applying rules for small, medium, and extra-large viewports and up.

```scss
div {
  // Shared rules.
  @include ct-breakpoint(s) {
    // Mobile-and-up Small rules.
  }
  @include ct-breakpoint(m) {
    // Mobile-and-up Medium rules.
  }
  @include ct-breakpoint(xl) {
    // Mobile-and-up Extra large rules.
  }
}

```

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

### Clear Drupal Caches using Drush

Source: https://github.com/civictheme/docs/blob/main/installation/govcms-content-provisioning.md

This command clears all caches in Drupal, which is often necessary after configuration changes or theme updates to ensure new settings are applied correctly. It's a standard maintenance task for Drupal sites.

```sh
ahoy drush cr

```

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

### Apply Spacing with ct-spacing() SCSS Function

Source: https://github.com/civictheme/docs/blob/main/development/uikit/extending-components/spacing.md

Demonstrates how to apply spacing (padding and margin) to elements using the `ct-spacing()` function in SCSS. This function converts spacing units based on the `$ct-spacing` variable, which defaults to `ct-particle()`.

```scss
div {
  padding: ct-spacing(1) ct-spacing(2);
  margin-bottom: ct-spacing(2);
}
```

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

### Component Implementation Pattern using Theme Mixin in SCSS

Source: https://github.com/civictheme/docs/blob/main/development/drupal-theme/systems/colors.md

A common SCSS pattern for implementing components that utilize the `ct-component-theme` mixin. This code applies theme-specific styles for primary tag variations.

```scss
.ct-tag {
  $root: &;

  // Base styles (shared across themes)
  border-radius: $ct-tag-border-radius;
  display: inline-block;

  // Theme-specific styles
  @include ct-component-theme($root) using($root, $theme) {
    &#{$root}--primary {
      @include ct-component-property($root, $theme, primary, background-color);
      @include ct-component-property($root, $theme, primary, border-color);
      @include ct-component-property($root, $theme, primary, color);
    }
  }
}
```

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

### Include and Preprocess Custom Field Logic (PHP)

Source: https://github.com/civictheme/docs/blob/main/development/drupal-theme/systems/mapping.md

This snippet shows how to include a custom field processing file and implement a preprocess hook in the subtheme's .theme file. It calls a custom preprocess function when the field preprocess hook is triggered, preparing data for component mapping.

```php
require_once __DIR__ . '/includes/custom_field.inc';

function subtheme_preprocess_field(array &$variables): void {
  _civictheme_preprocess_custom_field($variables);
}
```

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

### Component JavaScript Functionality (`.js`)

Source: https://github.com/civictheme/docs/blob/main/development/drupal-theme/systems/components.md

Provides interactive behavior and event handling for components using vanilla JavaScript. It manages component state, enhances accessibility, and utilizes `data-` attributes for element selection, avoiding dependencies on jQuery.

```javascript
/**
 * @file
 * Accordion behavior.
 */

(function (Drupal) {

  /**
   * Provides behavior for the accordion component.
   */
  Drupal.behaviors.civicThemeAccordion = {
    attach: function (context, settings) {
      // Select all accordions that are not yet processed.
      once('civicThemeAccordion', '[data-drupal-selector="*"].civic-accordion', context).forEach(accordionElement => {
        const trigger = accordionElement.querySelector('[data-drupal-selector="civic-accordion-trigger"]');
        const content = accordionElement.querySelector('[data-drupal-selector="civic-accordion-content"]');

        if (trigger && content) {
          trigger.addEventListener('click', () => {
            const isExpanded = trigger.getAttribute('aria-expanded') === 'true';
            trigger.setAttribute('aria-expanded', !isExpanded);
            content.hidden = !content.hidden;
          });
        }
      });
    }
  };

})(Drupal);

```

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

### Sass Breakpoint Mixin Usage in CivicTheme

Source: https://github.com/civictheme/docs/blob/main/development/uikit/components/grid.md

Illustrates how to use the `ct-breakpoint()` mixin in Sass to apply styles conditionally based on predefined breakpoints. This allows for responsive design by targeting specific viewport sizes, applying rules from smallest to largest.

```scss
div {
  // Shared rules.
  @include ct-breakpoint(s) {
    // Mobile-and-up Small rules.
  }
  @include ct-breakpoint(m) {
    // Mobile-and-up Medium rules.
  }
  @include ct-breakpoint(xl) {
    // Mobile-and-up Extra large rules.
  }
}
```

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

### Sass Breakpoint Definition for CivicTheme Grid

Source: https://github.com/civictheme/docs/blob/main/development/uikit/components/grid.md

Defines the breakpoint map used in the CivicTheme grid system. These breakpoints specify the minimum viewport widths at which different layout rules apply, from extra-extra-small (xxs) to extra-extra-large (xxl).

```scss
$ct-breakpoints: (
  'xxs': 0,
  'xs': 368px,
  's': 576px,
  'm': 768px,
  'l': 992px,
  'xl': 1280px,
  'xxl': 1440px,
);
```

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

### Define Default Typography with SCSS Map

Source: https://github.com/civictheme/docs/blob/main/development/uikit/components/typography.md

Establishes default typography styles using the `$ct-typography-default` SCSS map. Each key represents a typography style (e.g., 'heading-1'), and its value is a list defining size, line height, weight, font family, and letter spacing.

```scss
$ct-typography-default: (
  // Headings.
  'heading-1': (
    'xxs': ($ct-font-base-size * 2, $ct-font-base-line-height * 2.5, 700, 'primary', -0.6px),
    'm': ($ct-font-base-size * 3, $ct-font-base-line-height * 3.75, 700, 'primary', -1px)
  ),
  // ...
);
```

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

### Component Metadata and Schema (`.component.yml`)

Source: https://github.com/civictheme/docs/blob/main/development/drupal-theme/systems/components.md

Defines component properties, validation rules, and documentation using JSON Schema with Drupal's metadata schema. It serves as the single source of truth for component configuration, enabling automatic form generation in Storybook and Drupal.

```yaml
# Example *.component.yml structure
$schema: "https://raw.githubusercontent.com/civicrm/civicrm-core/master/tools/extensions/drupal/metadata.schema.json"
name: "Button"
status: "stable"
description: "A reusable button component."
props:
  label:
    type: "string"
    description: "The text displayed on the button."
    default: "Click Me"
  variant:
    type: "string"
    enum: ["primary", "secondary", "tertiary"]
    default: "primary"
  size:
    type: "string"
    enum: ["small", "medium", "large"]
    default: "medium"
```

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

### SCSS Breakpoint Definitions

Source: https://github.com/civictheme/docs/blob/main/development/uikit/extending-components/grid.md

Defines the breakpoint map for the CivicTheme grid system, specifying pixel values for various viewport sizes from extra-extra-small (xxs) to extra-extra-large (xxl).

```scss
$ct-breakpoints: (
  'xxs': 0,
  'xs': 368px,
  's': 576px,
  'm': 768px,
  'l': 992px,
  'xl': 1280px,
  'xxl': 1440px,
);

```

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

### Define Base Color Foundation in SCSS

Source: https://github.com/civictheme/docs/blob/main/development/drupal-theme/systems/colors.md

Defines the base semantic color tokens and their mappings for light and dark themes. This SCSS code sets up default color variables and provides functions for accessing color shades and tints.

```scss
// Brand colours can be extended
$ct-colors-brands: () !default;

// Default colour palette can be overridden
$ct-colors: () !default;

// Default semantic colour mapping
$ct-colors-default: (
  'light': (
    'heading': ct-color-shade(ct-color-constant-light('brand1'), 60),
    'body': ct-color-tint(ct-color-shade(ct-color-constant-light('brand1'), 80), 20),
    'background-light': ct-color-tint(ct-color-constant-light('brand2'), 90),
    'background': ct-color-constant-light('brand2'),
    'interaction-background': ct-color-constant-light('brand1'),
    'interaction-text': ct-color-tint(ct-color-constant-light('brand2'), 80),
    // ... more semantic colours
  ),
  'dark': (
    'heading': ct-color-tint(ct-color-constant-dark('brand1'), 95),
    'body': ct-color-tint(ct-color-constant-dark('brand1'), 85),
    'background': ct-color-constant-dark('brand2'),
    'interaction-background': ct-color-constant-dark('brand1'),
    'interaction-text': ct-color-constant-dark('brand2'),
    // ... more semantic colours
  )
);
```

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

### CivicTheme Update Commands (Drush & Ahoy)

Source: https://github.com/civictheme/docs/blob/main/development/drupal-theme/updating-civitheme-govcms-sass.md

This snippet provides the essential Drush and Ahoy commands required to update the CivicTheme. It includes running database updates, exporting configuration, and clearing the Drupal cache. These commands are typically executed locally after manually updating the theme files.

```sh
ahoy drush updb -y
ahoy drush cex -y
ahoy drush cr
```

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

### Manage CivicTheme Colors and Brand Colors via Drush

Source: https://github.com/civictheme/docs/blob/main/development/drupal-theme/color-selector.md

These Drush commands enable the Color Selector and Brand Colors, set specific brand colors, and clear the dynamic assets cache for CivicTheme. The 'civictheme:set-brand-colors' command requires a list of color values, and 'civictheme:clear-cache' ensures changes are applied.

```sh
# Enable Color Selector.
drush config-set civictheme.settings colors.use_color_selector 1

# Enable Brand Colors.
drush config-set civictheme.settings colors.use_brand_colors 1

# Set Brand Colors.
drush --include=path/to/civictheme/src/Drush civictheme:set-brand-colors light_brand1 light_brand2 light_brand3 dark_brand1 dark_brand2 dark_brand3

# Purge dynamic assets cache. Will be rebuilt during next pageload.
drush --include=path/to/civictheme/src/Drush civictheme:clear-cache
```

```sh
drush -y config-set civictheme.settings colors.use_color_selector 1
drush -y config-set civictheme.settings colors.use_brand_colors 1
drush --include=path/to/civictheme/src/Drush civictheme:set-brand-colors "#00698f" "#e6e9eb" "#121313" "#61daff" "#003a4f" "#00698f"
drush --include=path/to/civictheme/src/Drush civictheme:clear-cache
```

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

### Apply Component Color Variables in SCSS

Source: https://github.com/civictheme/docs/blob/main/development/drupal-theme/systems/colors.md

Illustrates how component variables automatically update to use custom brand or semantic colors. This SCSS code shows the direct referencing of semantic color functions.

```scss
// These automatically use your new colours
$ct-tag-light-primary-background-color: ct-color-light('interaction-background');
$ct-tag-light-primary-color: ct-color-light('interaction-text');
```

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

### Reference CivicTheme Tag Component in Twig (Twig)

Source: https://github.com/civictheme/docs/blob/main/development/drupal-theme/systems/mapping.md

This Twig template demonstrates how to reference a CivicTheme component, specifically the 'tag' component. It passes all available properties to the component and can be modified to include custom components.

```twig
{% include 'civictheme:tag' %}
```

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

### Override SCSS Variables for Color Customization

Source: https://github.com/civictheme/docs/blob/main/development/uikit/extending-components.md

This SCSS code sample demonstrates how to override base color variables in CivicTheme to customize the look and feel of components. It allows for extensive theming.

```scss
// Example of overriding SCSS color variables
$color-primary: #007bff;
$color-secondary: #6c757d;
// ... other color variables
```

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

### Extend Twig Components with Slots

Source: https://github.com/civictheme/docs/blob/main/development/uikit/extending-components.md

This Twig code snippet illustrates how to extend CivicTheme components using pre-defined slots. Slots are empty variables within Twig templates where custom HTML can be injected.

```twig
{# Example of a Twig component with an extendable slot #}
<div class="promo-card">
  <div class="promo-card__content">
    {{ promo_card_content | raw }}
  </div>
  {# This is an example of an extendable slot #}
  {% block promo_card_extra %}{% endblock %}
</div>
```

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

### Include Compiled CSS in Drupal Theme

Source: https://github.com/civictheme/docs/blob/main/development/drupal-theme/assets.md

This YAML defines a Drupal library that includes the compiled CSS file. This allows Drupal to recognize and load the theme's styles. The 'dist/civictheme.css' path assumes the compiled file is in the 'dist' directory of your theme.

```yaml
civictheme_custom_styles:
  version: VERSION
  css:
    component: ["dist/civictheme.css"]
```

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

### Placing Custom Icons in Assets

Source: https://github.com/civictheme/docs/blob/main/development/drupal-theme/assets.md

This instruction indicates the directory where custom SVG icons should be placed for use within the theme's SASS styles or templates. Icons in this directory can replace default icons if named the same.

```bash
cp your-icon.svg assets/icons/your-icon.svg
```

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

### CivicTheme Mixin for Applying Themes in SCSS

Source: https://github.com/civictheme/docs/blob/main/development/drupal-theme/systems/colors.md

The core SCSS mixin `ct-component-theme` used for applying theme-specific styles to components. It iterates through light and dark themes to apply content blocks.

```scss
@mixin ct-component-theme($name) {
  @each $theme in light, dark {
    &.ct-theme-#{$theme} {
      @content($name, $theme);
    }
  }
}
```

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

### Apply Typography with Mixin

Source: https://github.com/civictheme/docs/blob/main/development/uikit/components/typography.md

Applies pre-defined typography styles to HTML elements using the `ct-typography()` mixin. This mixin takes a typography mapping name as an argument to set the font properties for the selected element.

```scss
h1 {
  @include ct-typography('heading-l');
}
```

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

### Override CivicTheme Component with 'replaces' Key

Source: https://github.com/civictheme/docs/blob/main/development/drupal-theme/templates.md

This YAML configuration demonstrates how a custom theme can override an existing CivicTheme component. The 'replaces' key specifies the component to be replaced using the machine name of the theme/module and the component, separated by a colon. Both components must have compatible schemas defined in their respective YAML files.

```yaml
replaces: 'civictheme:button'
```

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

### SCSS Component Styles for Custom Tag Variant

Source: https://github.com/civictheme/docs/blob/main/development/drupal-theme/systems/colors.md

This SCSS code snippet adds styles for a new 'success' variant to the tag component. It uses the `ct-component-theme` mixin and `ct-component-property` to apply the custom properties defined for the success variant.

```scss
@include ct-component-theme($root) using($root, $theme) {
  // ... existing variants ...

  &#{$root}--success {
    @include ct-component-property($root, $theme, success, background-color);
    @include ct-component-property($root, $theme, success, border-color);
    @include ct-component-property($root, $theme, success, color);
  }
}
```

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

### Define Custom Brand Colors in SCSS

Source: https://github.com/civictheme/docs/blob/main/development/drupal-theme/systems/colors.md

An optional SCSS snippet to define custom brand colors for light and dark themes. This allows for brand-specific color palettes to be integrated into the CivicTheme system.

```scss
// In your theme's variables.base.scss
$ct-colors-brands: (
  'light': (
    'brand1': #0066cc,  // Primary brand colour
    'brand2': #f8f9fa,  // Secondary brand colour
    'brand3': #ff6b35,  // Accent brand colour
  ),
  'dark': (
    'brand1': #4d94ff,  // Primary brand colour (dark variant)
    'brand2': #1a1a1a,  // Secondary brand colour (dark variant)
    'brand3': #ff8c69,  // Accent brand colour (dark variant)
  )
);
```

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

### Include Compiled JavaScript in Drupal Theme

Source: https://github.com/civictheme/docs/blob/main/development/drupal-theme/assets.md

This YAML defines a Drupal library that includes the compiled JavaScript file. This enables the theme's JavaScript functionalities. The 'dist/civictheme.js' path assumes the compiled file is in the 'dist' directory of your theme.

```yaml
civictheme_custom_scripts:
  version: VERSION
  js:
    dist/civictheme.js: {}
  dependencies:
    - core/jquery
```

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

### SCSS Component Variables for Custom Tag Variant

Source: https://github.com/civictheme/docs/blob/main/development/drupal-theme/systems/colors.md

This SCSS code snippet defines component variables for a new 'success' variant of the tag component. It sets the background, border, and text colors for both light and dark themes, using the `ct-color-light` and `ct-color-dark` functions.

```scss
$ct-tag-light-success-background-color: ct-color-light('success') !default;
$ct-tag-light-success-border-color: $ct-tag-light-success-background-color !default;
$ct-tag-light-success-color: white !default;
$ct-tag-dark-success-background-color: ct-color-dark('success') !default;
$ct-tag-dark-success-border-color: $ct-tag-dark-success-background-color !default;
$ct-tag-dark-success-color: white !default;
```

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

### Define Default Fonts with SCSS Map

Source: https://github.com/civictheme/docs/blob/main/development/uikit/components/typography.md

Sets the default font families and their types using the `$ct-fonts-default` SCSS map. This map defines font families like 'primary' with their CSS `font-family` values and `uri` for font files or links.

```scss
$ct-fonts-default: (
  'primary': (
    'family': '"Lexend", sans-serif',
    'types': (
      (
        'uri': 'https://fonts.googleapis.com/css2?family=Lexend:wght@400;500;600;700&display=swap',
      ),
    ),
  ),
  // ...
);
```

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

### Extend Typography with SCSS Map

Source: https://github.com/civictheme/docs/blob/main/development/uikit/components/typography.md

Allows for custom typography styles by extending the `$ct-typography` SCSS map. This enables the definition of new typography variants like 'body-extra-large' with specific font properties.

```scss
$ct-typography: (
  'body-extra-large': (
    'xxs': ($ct-font-base-size * 2, $ct-font-base-line-height * 2.5, 700, 'primary', -0.6px),
    'm': ($ct-font-base-size * 3, $ct-font-base-line-height * 3.75, 700, 'primary', -1px)
  ),
);
```

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

### Define Component-Specific Color Variables in SCSS

Source: https://github.com/civictheme/docs/blob/main/development/drupal-theme/systems/colors.md

Sets component-specific color variables by mapping semantic colors to actual properties for different themes. These SCSS variables are crucial for maintaining consistent styling across components.

```scss
// Tag component variables
$ct-tag-light-primary-background-color: ct-color-light('interaction-background') !default;
$ct-tag-light-primary-color: ct-color-light('interaction-text') !default;
$ct-tag-dark-primary-background-color: ct-color-dark('interaction-background') !default;
$ct-tag-dark-primary-color: ct-color-dark('interaction-text') !default;
```

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

### SCSS Mixin for CSS Custom Properties Generation

Source: https://github.com/civictheme/docs/blob/main/development/drupal-theme/systems/colors.md

The `ct-component-property` SCSS mixin is used to generate CSS custom properties. It takes a variable number of arguments, with the last argument being the CSS property name. It relies on the `ct-component-var` mixin to resolve the actual CSS variable.

```scss
@mixin ct-component-property($args...) {
  $property: list.nth($args, list.length($args));
  #{$property}: ct-component-var($args...);
}
```