feat: Skeleton Plugin refactor #1660

AdrianGonz97 · 2023-06-11T17:57:18Z

Migration Guide

1. Install the new plugin:

npm install -D @skeletonlabs/tw-plugin

2. Update your `tailwind.config.[js,cjs,ts]`:

tailwind.config.cjs

// @ts-check <- Add this to the top of this file to enable type checking!

// 1. Import the new plugin
const { skeleton } = require('@skeletonlabs/tw-plugin');

/** @type {import('tailwindcss').Config} */
module.exports = {
	darkMode: 'class',
	content: [
		'./src/**/*.{html,js,svelte,ts}',
		require('path').join(require.resolve('@skeletonlabs/skeleton'), '../**/*.{html,js,svelte,ts}')
	],
	plugins: [
		// 2. Append the Skeleton plugin to the END of this list
		skeleton
	]
};

tailwind.config.js

// @ts-check <- Add this to the top of this file to enable type checking!
import { join } from 'path';

// 1. Import the new plugin
import { skeleton } from '@skeletonlabs/tw-plugin';

/** @type {import('tailwindcss').Config} */
export default {
	darkMode: 'class',
	content: [
		'./src/**/*.{html,js,svelte,ts}',
		join(require.resolve('@skeletonlabs/skeleton'), '../**/*.{html,js,svelte,ts}')
	],
	plugins: [
		// 2. Append the Skeleton plugin to the END of this list
		skeleton
	]
};

tailwind.config.ts

import { join } from 'path';
import type { Config } from 'tailwindcss';

// 1. Import the new plugin
import { skeleton } from '@skeletonlabs/tw-plugin';

const config = {
	darkMode: 'class',
	content: [
		'./src/**/*.{html,js,svelte,ts}',
		join(require.resolve('@skeletonlabs/skeleton'), '../**/*.{html,js,svelte,ts}')
	],
	plugins: [
		// 2. Append the Skeleton plugin to the END of this list
		skeleton
	]
} satisfies Config;

export default config;

3. Add your theme:

Next, we'll need to pass your previous theme to the plugin.

Note: Previously known as "Extras", "Enhancements" provided additional settings such as background gradients, header font weights, and more. Previously, they were enabled when data-theme was set to the name of your theme on the body tag in app.html.

Preset theme without any enhancements

// tailwind.config.[cjs|js|ts]

// ...

	plugins: [
		skeleton({
			themes: {
				// if we were using `theme-skeleton.css`
				preset: [ "skeleton" ] 
			}
		})
	]

// ...

Preset theme with enhancements

// tailwind.config.[cjs|js|ts]

// ...

	plugins: [
		skeleton({
			themes: {
				// if we were using `theme-skeleton.css` with enhancements
				preset: [ { name: "skeleton", enhancements: true } ] 
			}
		})
	]

// ...

Custom theme

If you have made your own custom theme, here's a quick guide on how to convert it into a compatible format:

Visit https://transform.tools/css-to-js
Copy the contents of your theme's :root selector and paste them into the CSS field on the site.
Copy the converted property values. (note: don't copy the wrapping converted object, but instead, only copy the values defined within the object).
Paste the converted properties into the properties field (shown below).

// tailwind.config.[cjs|js|ts]

// ...

	plugins: [
		skeleton({
			themes: {
				custom: [
					{
						name: 'custom-theme-name',
						properties: {
							// paste your custom theme properties here...
							
							// for example:
							"--theme-font-family-base": "system-ui, sans-serif",
							"--theme-font-family-heading": "'Quicksand', sans-serif",
							"--theme-font-color-base": "var(--color-surface-900)",
							"--theme-font-color-dark": "var(--color-surface-50)"
							// ... and so on
						}
					}
				]
			}
		})
	]

// ...

Keep in mind that this is still Javascript, so you are free to define the theme properties in a sperate file, export it as an object, and import it into your tailwind.config.[cjs|js|ts] as a module (if you wish to keep your tailwind config as minimal as possible).

4. Add your theme's name to your `src/app.html`:

We'll need to add the name of your theme to the data-theme attribute on the body tag. Themes can easily be switched by changing the value of this attribute.

<html lang="en" class="dark">

	<!-- ... -->

	<!-- Add the name of your theme here -->
	<body data-theme="my-theme-name">
		<div class="h-full overflow-hidden contents">%sveltekit.body%</div>
	</body>
</html>

5. Add tailwind directives to `src/app.postcss`:

/* app.postcss */

/* these must be added to the very top */
@tailwind base;
@tailwind components;
@tailwind utilities;
@tailwind variants;

/* rest of your global styles go below... */

6. Remove stylesheet imports from your root `+layout.svelte`:

<!--  src/routes/+layout.svelte -->

<script>
	// delete the theme and core stylesheet
-	import '@skeletonlabs/skeleton/themes/theme-skeleton.css';
-	import '@skeletonlabs/skeleton/styles/skeleton.css';

	import '../app.postcss'; // keep this
</script>

Description

Closes #1286

This is a complete overhaul of our skeleton plugin. The plugin has been extracted out into it's own package. Users will now only have to import our plugin instead of having to add all of our stylesheets (woohoo!).

Stylesheets have also been grouped by their respective layers, base or components. This needed to be done for the sake of adding the base styles and component classes separately to the plugin.

TODO

Additional Notes

~~For some reason, tailwind 3.3.2 breaks our gradients for variants. The plugin will stick with 3.3.1 for the time being. See this deployment.~~ ...It works now for some reason.
Initial load times for our docs site now seem to be faster on the dev server.
It looks like we can now use Skeleton specific component classes in .css and .postcss files now.

Checklist

Please read and apply all contribution requirements.

This PR targets the dev branch (NEVER master)
Documentation reflects all relevant changes
Branch is prefixed with: docs/, feat/, chore/, bugfix/
Ensure Svelte and Typescript linting is current - run pnpm check
Ensure Prettier linting is current - run pnpm format
All test cases are passing - run pnpm test
Includes a changeset (if relevant; see above)

changeset-bot · 2023-06-11T17:57:21Z

⚠️ No Changeset found

Latest commit: ae55797

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

vercel · 2023-06-11T17:57:21Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
skeleton-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jul 5, 2023 8:49pm

…orepo root

endigo9740 · 2023-06-21T16:44:42Z

@AdrianGonz97 sorry I missed you comment a few days go. GitHub keeps notifying me of updates to the PR, but just links me to the list of file changes!

After giving it some thought, I'm thinking about removing the enhancements (formerly known as extras) field out of the CustomThemeConfig type. It's a bit out of the scope of the plugin and will probably lead to more confusion about it's purpose (especially with the caveat that users have prefix the property key with "[data-theme='my-custom-theme'] ...").

I think we mentioned this in our prior discussion, but really the "extras" needs to go away and those need to become standardized but optional CSS custom properties that are part of the theme. Perhaps we even document how to extend the theme with unique properties. The idea being that we want folks to buy into the design token approach, rather than circumvent or duplicate effort.

I don't know exactly how this will look in execution, so I'll have to tinker with it a bit when we start the theme generator updates. I'm thinking order of operations look like this:

Complete work on the new Tailwind plugin (as much as possible)
Merge that into the v2 branch
Create a new feature branch off of v2, implement the theme generator updates
This allows us to synchronize theme generator and plugin revisions

The end result is what is shipped in v2

AdrianGonz97 · 2023-06-21T16:58:53Z

@endigo9740 Alright, that sounds good. In that case, I think this PR is practically ready to be merged. The only remaining task would be to update our manual install documentation and add a section explaining how the plugin works, customization, etc.

endigo9740 · 2023-06-21T17:04:55Z

@AdrianGonz97 I agreed, we definitely need to get that doc page started.

A couple other things:

I've completed my audit of the stylesheets and found no other duplicate styles between /base and /components
I've revised the checklist above slightly. Just note that I've nixed the idea of migrating variants to the looped CSS-in-JS approach that we use for design tokens. Some of the styles (ex: ring) are too complex to replicate. Let's circle back to that in a later revision. For now keep these as is.

Per what's remaining:

I believe gradient variants are still broken in the newest release of Tailwind, correct?
We still need to settle on the process for installation of the plugin. If we can make it a peer dependency that would be ideal. If for some reason we don't, @niktek needs to be looped in to update the CLI to handle this.
I'll be noodling on the theme and theme generator updates to support the "extras" as mentioned above
We really need a proper name for this :D

AdrianGonz97 added 12 commits June 10, 2023 11:11

initial plugin core

6b80814

oops

f699496

replace class generator for a smaller and faster base styles generator

283ab70

replace for ts config

fe83bb5

export as esm

9c1b2cf

esm modules

e599b96

target commonjs because of TW

939e73e

split the styles into their respective layers

a4e822f

export the plugin

93147ed

export dts

50dca96

export the plugin as default

a21f47c

fixed import

9f2e3fe

vercel bot had a problem deploying to Preview June 11, 2023 17:57 Failure

AdrianGonz97 added 3 commits June 11, 2023 13:58

added sync

b0b907a

cleanup

5bd4ab8

added component classes to base style compilation

e9bbfc5

vercel bot deployed to Preview June 11, 2023 18:01 View deployment

ignore generated

2a32baf

vercel bot deployed to Preview June 11, 2023 18:04 View deployment

added file watcher

faa94b3

vercel bot deployed to Preview June 11, 2023 19:46 View deployment

AdrianGonz97 added 3 commits June 11, 2023 15:48

fix

724daed

stop the warning

5abf488

add plugin to workspace

2f8f2f7

vercel bot deployed to Preview June 11, 2023 20:47 View deployment

AdrianGonz97 added 3 commits June 11, 2023 16:52

no need for exports

8dde304

fix import

db7199b

added docs for config options

75f19eb

removed elements dir

ab87ef6

vercel bot had a problem deploying to Preview June 17, 2023 15:38 Failure

forgot to hit the save button

5a10f4c

vercel bot deployed to Preview June 17, 2023 15:45 View deployment

ignore dist

933f76e

vercel bot deployed to Preview June 19, 2023 15:04 View deployment

added dev script to start the docs site and plugin watcher from mon…

f6ddc94

…orepo root

vercel bot deployed to Preview June 20, 2023 15:29 View deployment

Merge remote-tracking branch 'upstream/dev' into feat/plugin-refactor

37b91da

vercel bot deployed to Preview June 20, 2023 19:18 View deployment

update tailwind version

64cefe9

vercel bot deployed to Preview June 21, 2023 17:42 View deployment

endigo9740 mentioned this pull request Jul 4, 2023

Resolve issue with button groups and child variant precedence #1725

Closed

AdrianGonz97 added 3 commits July 5, 2023 16:44

update plugin name

65b2eff

moved btn disabled selector

c03441a

plugin name

9436cca

vercel bot deployed to Preview July 5, 2023 20:45 View deployment

Merge branch 'v2' into feat/plugin-refactor

ae55797

vercel bot deployed to Preview July 5, 2023 20:49 View deployment

AdrianGonz97 merged commit dbd2ec0 into skeletonlabs:v2 Jul 5, 2023
3 checks passed

endigo9740 mentioned this pull request Jul 19, 2023

v2 Support for Theme Generator #1781

Closed

endigo9740 mentioned this pull request Jul 28, 2023

Ability to Add New Colors #1800

Closed

endigo9740 mentioned this pull request Aug 8, 2023

Implement support for Skeleton v2 skeletonlabs/create-skeleton-app#37

Closed

9 tasks

github-actions bot mentioned this pull request Aug 10, 2023

chore(release): version package (rc) #1841

Merged

This was referenced Aug 28, 2023

chore(release): version package #1958

Closed

chore(release): version package #1963

Merged

AdrianGonz97 mentioned this pull request Sep 8, 2023

Enhancements on Custom Themes #2011

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Skeleton Plugin refactor #1660

feat: Skeleton Plugin refactor #1660

AdrianGonz97 commented Jun 11, 2023 •

edited

changeset-bot bot commented Jun 11, 2023 •

edited

vercel bot commented Jun 11, 2023 •

edited

endigo9740 commented Jun 21, 2023 •

edited

AdrianGonz97 commented Jun 21, 2023

endigo9740 commented Jun 21, 2023 •

edited

feat: Skeleton Plugin refactor #1660

feat: Skeleton Plugin refactor #1660

Conversation

AdrianGonz97 commented Jun 11, 2023 • edited

Migration Guide

1. Install the new plugin:

2. Update your tailwind.config.[js,cjs,ts]:

tailwind.config.cjs

tailwind.config.js

tailwind.config.ts

3. Add your theme:

Preset theme without any enhancements

Preset theme with enhancements

Custom theme

4. Add your theme's name to your src/app.html:

5. Add tailwind directives to src/app.postcss:

6. Remove stylesheet imports from your root +layout.svelte:

Description

TODO

Additional Notes

Checklist

changeset-bot bot commented Jun 11, 2023 • edited

⚠️ No Changeset found

vercel bot commented Jun 11, 2023 • edited

endigo9740 commented Jun 21, 2023 • edited

AdrianGonz97 commented Jun 21, 2023

endigo9740 commented Jun 21, 2023 • edited

AdrianGonz97 commented Jun 11, 2023 •

edited

2. Update your `tailwind.config.[js,cjs,ts]`:

4. Add your theme's name to your `src/app.html`:

5. Add tailwind directives to `src/app.postcss`:

6. Remove stylesheet imports from your root `+layout.svelte`:

changeset-bot bot commented Jun 11, 2023 •

edited

vercel bot commented Jun 11, 2023 •

edited

endigo9740 commented Jun 21, 2023 •

edited

endigo9740 commented Jun 21, 2023 •

edited