Creating a custom Foundation subtheme

TL;DR

Create a subtheme using drush

1. cd into the same level as the theme folder (usually web/ if you're using Composer)
2. Ensure zurb_foundation contrib theme is enabled: drush en zurb_foundation (drush 8 command)
3. Create the subtheme: drush fst mycustomtheme
4. Type y to enable the subtheme
5. Move themes/contrib/mycustomtheme into themes/custom (create the custom/ folder if required)
6. Set subtheme to default - Appearance

Create subtheme manually

1. Copy the folder themes/contrib/zurb_foundation/STARTER to themes/custom (create the custom/ folder if required)
2. Find and replace STARTER (capitals only) in all files to be the machine name of your subtheme (eg. mycustomtheme). (for macOS/BSD this might work `find . \! \( -type d -or -name \*.png -or -name \*.svg -or -name \*.ico -or -name \*.gif  -or -name \*.jpg \)  -type f -print0 | xargs -0 sed -i '' 's/STARTER/mycustomtheme/g'`)
3. Remove the .txt extension from STARTER.info.yml.txt
4. Rename all files beginning with STARTER to your subtheme machine name (for macOS/BSD this might work: `find . -type f -exec rename 's/STARTER/mycustomtheme/' '{}' \;`
5. In your Drupal admin, go to Appearance. Enable your new subtheme and set it to default

Update your theme's details and thumbnail image

1. Edit the .info.yml with your theme details
2. Create a screenshot.jpg file (368px × 321px) and save it in the subtheme images/ folder.
3. Uncomment the screenshot line (around line 8)

Why create a subtheme?

We HIGHLY recommend that you create a subtheme, a child theme, to the Drupal ZURB Foundation theme (D8F6). This is so when new updates are applied to the D8F6 theme, your subtheme isn't affected by the changes, and can inherit any new features and fixes.

There are a couple of ways to do this.

Use drush to create your Foundation subtheme.

You know what drush is, right? It's basically command-line access to common Drupal administrative tasks and configuration.

You can create your D8F6 subtheme with a simple drush command. And you can call your subtheme anything you like.

What about Drush 9

At the time of writing this, the Foundation subtheme command isn't available in Drush 9. You can view and follow this issue for more details: https://www.drupal.org/project/zurb_foundation/issues/2920472

Using Drush 8

Change directory into your Drupal project (into the same folder level as your core, modules and themes folders - usually the web/ or public_html/ folder if you've used Composer).

cd web

You'll need to ensure that the ZURB Foundation theme you installed previously is enabled. You can do that using the following drush 8 command:

drush en zurb_foundation -y

For the sake of this example, let's call your subtheme "My Custom Theme" (of course, replace "My Custom Theme" with whatever you like). Change the name to use only lowercase letters, numbers and no spaces.

drush fst mycustomtheme

It will ask you if you'd like to enable your theme. Simply type y to do this:

The following extensions will be enabled: mycustomtheme
Do you really want to continue? (y/n):

Add a description on the fly.

It's not necessary (you can do this step later) but if you like, you can use a slightly longer command to create a description for your subtheme. 

Instead of the above command, use:

drush fst mycustomtheme --description="My super sweet awesome theme"

Move your subtheme into a custom folder.

By default, the drush command places your theme into the themes/contrib folder. We encourage you to follow conventional Drupal 8 folder structure and move your subtheme into a custom/ folder.

With command line:

mkdir themes/custom

mv -v themes/contrib/mycustomtheme/ themes/custom/

You can also do this manually.

Create a new directory in the themes/ folder named custom

Click and drag the mycustomtheme folder from themes/contrib to themes/custom

Set your subtheme to default using drush

Use the following drush command to set your new subtheme as the default theme:

drush vset theme_default mycustomtheme

Now if you log in to your Drupal website in your browser and navigate to the Appearance tab, you'll see your subtheme.

Set it to enabled and set to default (if you haven't already, enable the ZURB Foundation theme as well).

Scroll further down to find instructions for updating your theme details and creating a custom thumbnail image.

Manually create your subtheme

Don't want to use drush? Or do you have Drush 9 installed? We have a STARTER folder that you can create your subtheme with.

For the sake of this example, let's call your subtheme "My Custom Theme" (of course, replace "My Custom Theme" with whatever you like).

1. Expand the themes/contrib/zurb_foundation folder.
2. Copy the STARTER folder into themes/custom (create the custom folder if it doesn't exist yet) and rename it, using only letters and number. No spaces. This is the machine name. eg. mycustomtheme
3. Expand your new subtheme folder.
4. Update the STARTER.info.yml.txt
   1. Open the STARTER.info.yml.txt and use a find-and-replace to replace STARTER with your subtheme machine name eg. mycustomtheme
   2. Rename the STARTER.info.yml.txt with your subtheme's machine name AND remove the .txt extension. eg. mycustomtheme.info.yml
5. Update STARTER.libraries.yml
   1. Open the STARTER.libraries.yml and use a find-and-replace to replace STARTER with your subtheme machine name eg. mycustomtheme
   2. Rename STARTER.libraries.yml eg. mycustomtheme.libraries.yml
6. Update the STARTER.theme
   1. Open the STARTER.theme and use a find-and-replace to replace STARTER with your subtheme machine name eg. mycustomtheme
   2. Rename STARTER.theme eg. mycustomtheme.theme
7. Open the package.json and update line 2; replace STARTER with your subtheme machine name eg. mycustomtheme
8. Open the theme-settings.php and use a find-and-replace to replace STARTER with your subtheme machine name eg. mycustomtheme
9. Expand the css/ folder and rename STARTER.css eg. mycustomtheme.css
10. Expand the js/ folder and rename STARTER.js eg. mycustomtheme.js
11. Expand the scss/ folder and rename STARTER.scss eg. mycustomtheme.scss

As a final check, if you can search your subtheme folder for any instances of STARTER (search uppercase only), and if you've missed any, update them to your subtheme's machine name.

Update your Foundation subtheme details and thumbnail image

Edit the .info.yml (eg. mycustomtheme.info.yml) and update the following.

• name
• description

You can create a custom theme thumbnail image (we recommend 368 pixels × 321 pixels, 72DPI - or use the themes/contrib/zurb_foundation/images/screenshot.jpg image filed to get the right image dimensions). Place that image in your subtheme's images folder and name it screenshot.jpg

Around line 8 of the subtheme's .info.yml file, uncomment screenshot (ie. remove the # at the start of that line).

Clear the cache of your Drupal website and in the Appearance tab, you should see your subtheme has updated name, description and thumbnail image.

What's next?

Install the NPM dependencies that come with your new subtheme.