PWA-2915: Added Tailwind CSS configuration and theming documentation #155

bdenham · 2022-09-30T19:03:26Z

Description

This PR adds documentation for configuring and customizing Tailwind and Venia themes.

Staged Preview

https://developer-stage.adobe.com/commerce/pwa-studio/guides/theming

Related Issue

PWA-2915

Motivation and Context

Provide docs for existing Tailwind CSS theming in PWA Studio.

How Has This Been Tested?

Created a PWA Studio app from the create-pwa CLI and applied the examples to it to see the expected results.

Screenshots (if appropriate):

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)

keharper

I think it's premature to change the theme. Theme changes shouldn't be made in a content branch anyway. Please back out those changes, and we'll talk about the benefits and repercussions of changing the theme at our next meeting.

keharper

I was fooled by the intro/step 1, thinking the topic is of limited use for those who installed with the CLI. As a result, some of my suggestions maybe aren't applicable. I'm not going to delete/amend them, because you should know what a reader could experience.

keharper · 2022-09-30T20:44:29Z

src/pages/guides/theming/index.md

+
+# Theming PWA Studio apps
+
+When creating a new PWA Studio app with [@magento/create-pwa](https://www.npmjs.com/package/@magento/create-pwa), theming is configured out of the box to use Tailwind CSS. The CLI installs all the supporting Tailwind CSS packages and configuration files described below. For a PWA Studio app that was not scaffolded with the CLI, this topic describes how to configure your app for theming with Tailwind CSS.


Consider specifying the exact command in the second sentence.

Start a new paragraph with the sentence that begins with "For a". Maybe even make it a note. People skim intros, and we don't want someone who ran the command be under the impression they also have to do all these steps. Also consider stating CLI users should do next, since there's nothing else to do here.

src/pages/guides/theming/index.md

keharper · 2022-09-30T20:58:12Z

src/pages/guides/theming/index.md

+After installation, your `package.json` file should contain the following entries:
+
+```json
+// package.json


This is causing all sorts of GH rendering problems. It's not necessary, since you listed it in the lead-in sentence.

src/pages/guides/theming/index.md

keharper · 2022-09-30T22:15:00Z

src/pages/guides/theming/index.md

+
+## Step 3: Test your configuration
+
+To test your configuration with the `[venia]` theme set as a `preset` in your config file, add the following `theme` style override and rebuild your app.


At the beginning of this topic, you described that it was meant for those who didn't use the default scaffolding. I was willing to give the benefit of the doubt that step 2 was just for setting up in an alternate environment, but really, it does contain advice for changing the defaults. As of this step though, it's clear that it applies to everyone.

Rewrite the intro and make sure it's clear that

Step 1 provides details about the two installation paths

Alternate scaffolding users must go through step 2, but the happy path installers might need to make changes from the default configuration

Steps 3 and 4 are for everyone.

Below, in option 2, you say modifying the config.js file isn't the right thing to do in most cases. I recommend saying that this step is a quick test, and you might want to back out these changes when creating your own presets.

keharper · 2022-09-30T22:36:27Z

src/pages/guides/theming/index.md

+
+### Option 1: Update tailwind.config.js theme directly
+
+If you followed Step 3 above, you have already done this as a test. Another example: change the default font family by adding new styles to the `tailwind.config.js` `theme` property:


I would assume that the reader followed step 3 (no need to write "above"). Add the fontFamily example below to step 3, and use this section point out this is what you did, but you probably don't want to use it in a real-world scenario.

keharper · 2022-09-30T22:42:53Z

src/pages/guides/theming/index.md

+
+### Override or extend Tailwind base styles
+
+To override or extend the Tailwind base styles for version `2.2.19`, and any other version, use this site as a [reference to the Tailwind base styles](https://unpkg.com/browse/tailwindcss@2.2.19/stubs/defaultConfig.stub.js).


Can you say something like "the base styles for any supported version of TW"? Again, trying to future-proof the docs.

src/pages/guides/theming/index.md

bdenham · 2022-10-03T13:56:01Z

I think it's premature to change the theme.

I agree. This was a test that I should have mentioned in the PR description. Until this, I've never tried applying an npm dependency on the commerce-theme outside the project's internal example project. This was part of that testing (via the GitHub staging build workflow) to see the results. And the results proved that the existing setup (for version 0.0.2) needs some adjustments. I'll make sure it's set back to normal.

Co-authored-by: Kevin Harper <keharper@users.noreply.github.com>

…lace

…place

keharper

Looking much better. You can accept/reject my suggestions.

src/pages/guides/theming/index.md

Co-authored-by: Kevin Harper <keharper@users.noreply.github.com>

bdenham · 2022-10-05T17:31:19Z

@keharper They look good to me. Thanks.

jcalcaben

just one minor suggestion, but looks good otherwise

src/pages/guides/theming/index.md

Co-authored-by: James Calcaben <jcalcaben@users.noreply.github.com>

bdenham added 3 commits September 19, 2022 08:06

feat(theming): add theming instructions

2aff97f

Merge branch 'main' of https://github.com/AdobeDocs/commerce-pwa-studio

4f010cc

docs(theming): add tailwind configuration and customization instructions

670f165

bdenham added documentation enhancement New feature or request labels Sep 30, 2022

bdenham requested review from jcalcaben and keharper September 30, 2022 19:03

bdenham self-assigned this Sep 30, 2022

fix: delete trailing space to fix linter error

9d7b1af

bdenham changed the title ~~Pwa 2915~~ PWA-2915: Added Tailwind CSS configuration and theming documentation Sep 30, 2022

keharper requested changes Sep 30, 2022

View reviewed changes

keharper reviewed Sep 30, 2022

View reviewed changes

bdenham and others added 2 commits October 3, 2022 09:41

Apply suggestions from code review

ae44f7f

Co-authored-by: Kevin Harper <keharper@users.noreply.github.com>

docs(review): updated instructions based on first review

76d2973

bdenham requested a review from keharper October 4, 2022 18:55

bdenham added 5 commits October 4, 2022 14:14

fix(docs): update code block to prevent GitHub from blooding-up the p…

c61eb78

…lace

fix(docs): update code block to prevent GitHub from bloodying-up the …

0da1926

…place

Merge branch 'main' into PWA-2915

09e79c6

chore(merge): sync with main updates

ac58b51

docs(updates): simplify section titles

a7cc65b

keharper approved these changes Oct 4, 2022

View reviewed changes

src/pages/guides/theming/index.md Outdated Show resolved Hide resolved

src/pages/guides/theming/index.md Outdated Show resolved Hide resolved

src/pages/guides/theming/index.md Outdated Show resolved Hide resolved

Apply suggestions from code review

000a30a

Co-authored-by: Kevin Harper <keharper@users.noreply.github.com>

bdenham added 6 commits October 6, 2022 11:31

fix: update headings and format code samples

1014fbd

fix: minor headings and formatting updates

2d9851d

fix: add language tweaks and frontmatter

c846dfa

fix: add line between header and paragraph

41ec7b6

fix: format keywords properly

381a7bd

fix: add a bit more explicit instructions

79bd883

fix: grammatical error

ae72b65

jcalcaben approved these changes Oct 7, 2022

View reviewed changes

src/pages/guides/theming/index.md Outdated Show resolved Hide resolved

Update src/pages/guides/theming/index.md

b54d894

Co-authored-by: James Calcaben <jcalcaben@users.noreply.github.com>

bdenham merged commit 782bad4 into main Oct 7, 2022

bdenham deleted the PWA-2915 branch October 7, 2022 20:33

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

PWA-2915: Added Tailwind CSS configuration and theming documentation #155

PWA-2915: Added Tailwind CSS configuration and theming documentation #155

bdenham commented Sep 30, 2022 •

edited

keharper left a comment •

edited

keharper left a comment

keharper Sep 30, 2022

keharper Sep 30, 2022

keharper Sep 30, 2022

keharper Sep 30, 2022

keharper Sep 30, 2022

keharper Sep 30, 2022

bdenham commented Oct 3, 2022

keharper left a comment

bdenham commented Oct 5, 2022

jcalcaben left a comment


		# Theming PWA Studio apps

		When creating a new PWA Studio app with [@magento/create-pwa](https://www.npmjs.com/package/@magento/create-pwa), theming is configured out of the box to use Tailwind CSS. The CLI installs all the supporting Tailwind CSS packages and configuration files described below. For a PWA Studio app that was not scaffolded with the CLI, this topic describes how to configure your app for theming with Tailwind CSS.


		## Step 3: Test your configuration

		To test your configuration with the `[venia]` theme set as a `preset` in your config file, add the following `theme` style override and rebuild your app.


		### Option 1: Update tailwind.config.js theme directly

		If you followed Step 3 above, you have already done this as a test. Another example: change the default font family by adding new styles to the `tailwind.config.js` `theme` property:


		### Override or extend Tailwind base styles

		To override or extend the Tailwind base styles for version `2.2.19`, and any other version, use this site as a [reference to the Tailwind base styles](https://unpkg.com/browse/tailwindcss@2.2.19/stubs/defaultConfig.stub.js).

PWA-2915: Added Tailwind CSS configuration and theming documentation #155

PWA-2915: Added Tailwind CSS configuration and theming documentation #155

Conversation

bdenham commented Sep 30, 2022 • edited

Description

Staged Preview

Related Issue

Motivation and Context

How Has This Been Tested?

Screenshots (if appropriate):

Types of changes

keharper left a comment • edited

Choose a reason for hiding this comment

keharper left a comment

Choose a reason for hiding this comment

keharper Sep 30, 2022

Choose a reason for hiding this comment

keharper Sep 30, 2022

Choose a reason for hiding this comment

keharper Sep 30, 2022

Choose a reason for hiding this comment

keharper Sep 30, 2022

Choose a reason for hiding this comment

keharper Sep 30, 2022

Choose a reason for hiding this comment

keharper Sep 30, 2022

Choose a reason for hiding this comment

bdenham commented Oct 3, 2022

keharper left a comment

Choose a reason for hiding this comment

bdenham commented Oct 5, 2022

jcalcaben left a comment

Choose a reason for hiding this comment

bdenham commented Sep 30, 2022 •

edited

keharper left a comment •

edited