V2 Theme generator and doc updates (#1816)

Co-authored-by: AdrianGonz97 <31664583+AdrianGonz97@users.noreply.github.com>
skeletonlabs · Aug 4, 2023 · 32583dc · 32583dc
1 parent 2eaef8b
commit 32583dc
Show file tree

Hide file tree

Showing 7 changed files with 403 additions and 144 deletions.
diff --git a/sites/skeleton.dev/src/lib/layouts/DocsThemer/DocsThemer.svelte b/sites/skeleton.dev/src/lib/layouts/DocsThemer/DocsThemer.svelte
@@ -40,6 +40,7 @@
 
 	// Local
 	let cssOutput = '';
+	let cssInJsOutput = '';
 	let showThemeCSS = false;
 	let conReports: ContrastReport[] = getContrastReports();
 
@@ -51,6 +52,7 @@
 		});
 	}
 
+	// CSS output (for live preview)
 	function generateColorCSS(): string {
 		let newCSS = '';
 		const newPalette: Record<string, Palette> = {};
@@ -69,6 +71,25 @@
 		return newCSS;
 	}
 
+	// CSS-in-JS output (for theme file)
+	function generateColorCssInJS(): string {
+		let newCssInJs = '';
+		const newPalette: Record<string, Palette> = {};
+		// Loop store colors
+		$storeThemGenForm.colors.forEach((color: ColorSettings, i: number) => {
+			const colorKey = color.key;
+			// Generate the new color palette hex/rgb/on values
+			newPalette[color.key] = generatePalette($storeThemGenForm.colors[i].hex);
+			// The color set comment
+			newCssInJs += `// ${colorKey} | ${newPalette[colorKey][500].hex} \n\t\t`;
+			// CSS props for shade 50-900 per each color
+			for (let [k, v] of Object.entries(newPalette[colorKey])) {
+				newCssInJs += `"--color-${colorKey}-${k}": "${v.rgb}", // ${v.hex}\n\t\t`;
+			}
+		});
+		return newCssInJs;
+	}
+
 	function onPreviewToggle(): void {
 		if ($storePreview === false) {
 			localStorage.removeItem('storeThemGenForm');
@@ -104,6 +125,7 @@
 	}
 
 	$: if ($storeThemGenForm && hexValuesAreValid($storeThemGenForm.colors)) {
+		// CSS output (for live preview)
 		cssOutput = `
 :root {
 	/* =~= Theme Properties =~= */
@@ -124,6 +146,32 @@
 	--on-surface: ${$storeThemGenForm.colors[6]?.on};
 	/* =~= Theme Colors  =~= */
 	${generateColorCSS()}
+}`;
+		// CSS-in-JS output (for theme file)
+		cssInJsOutput = `
+import type { CustomThemeConfig } from '@skeletonlabs/tw-plugin';\n
+export const myCustomTheme: CustomThemeConfig = {
+    name: 'my-custom-theme',
+    properties: {
+		// =~= Theme Properties =~=
+		"--theme-font-family-base": "${fontSettings[$storeThemGenForm.fontBase]}",
+		"--theme-font-family-heading": "${fontSettings[$storeThemGenForm.fontHeadings]}",
+		"--theme-font-color-base": "${$storeThemGenForm.textColorLight}",
+		"--theme-font-color-dark": "${$storeThemGenForm.textColorDark}",
+		"--theme-rounded-base": "${$storeThemGenForm.roundedBase}",
+		"--theme-rounded-container": "${$storeThemGenForm.roundedContainer}",
+		"--theme-border-base": "${$storeThemGenForm.borderBase}",
+		// =~= Theme On-X Colors =~=
+		"--on-primary": "${$storeThemGenForm.colors[0]?.on}",
+		"--on-secondary": "${$storeThemGenForm.colors[1]?.on}",
+		"--on-tertiary": "${$storeThemGenForm.colors[2]?.on}",
+		"--on-success": "${$storeThemGenForm.colors[3]?.on}",
+		"--on-warning": "${$storeThemGenForm.colors[4]?.on}",
+		"--on-error": "${$storeThemGenForm.colors[5]?.on}",
+		"--on-surface": "${$storeThemGenForm.colors[6]?.on}",
+		// =~= Theme Colors  =~=
+		${generateColorCssInJS()}
+	}
 }`;
 	}
 
@@ -302,11 +350,11 @@
 
 		<!-- CSS Output -->
 		<footer class="col-span-2 space-y-4">
-			{#if showThemeCSS}<CodeBlock language="css" code={cssOutput} />{/if}
+			{#if showThemeCSS}<CodeBlock language="ts" code={cssInJsOutput} />{/if}
 			<div class="card variant-glass p-4 text-center">
 				<!-- prettier-ignore -->
 				<button class="btn btn-lg variant-filled-primary font-bold" on:click={() => { showThemeCSS = !showThemeCSS; }} disabled={!$storePreview}>
-					{!showThemeCSS ? 'Show' : 'Hide'} Theme CSS
+					{!showThemeCSS ? 'Show' : 'Hide'} Theme Source
 				</button>
 			</div>
 		</footer>

diff --git a/sites/skeleton.dev/src/routes/(inner)/docs/generator/+page.svelte b/sites/skeleton.dev/src/routes/(inner)/docs/generator/+page.svelte
@@ -21,24 +21,58 @@
 
 	<hr />
 
-	<!-- Instructions -->
+	<!-- Implement (v2) -->
 	<section class="space-y-4">
-		<h2 class="h2">Importing Your Theme</h2>
+		<h2 class="h2">How to Implement</h2>
+		<!-- prettier-ignore -->
 		<p>
-			Copy and paste your theme CSS into <code class="code">/src/theme.postcss</code>, then import the theme into your root layout in
-			<code class="code">/src/routes/+layout.svelte</code> instead of a premade Skeleton theme. Keep the order as shown.
+			Generate your theme above, copy the source code, then paste this into a new file in the root of your project with a distinct name, such as: <code class="code">my-custom-theme.[ts|js]</code>. If you opt for the Javascript format, make sure to strip out any Typescript type information.
 		</p>
+		<!-- Instruction -->
+		<p>Open <code class="code">tailwind.config.[cjs|js|ts]</code> found in the root of your project, and import your custom theme.</p>
+		<CodeBlock language="ts" code={`import { myCustomTheme } from './my-custom-theme'`} />
+		<p>Within this file, register your custom theme via the Skeleton Tailwind plugin settings.</p>
 		<CodeBlock
 			language="ts"
 			code={`
-// Your custom Skeleton theme:
-import '../theme.postcss';\n
-// This contains the bulk of Skeletons required styles:
-import '@skeletonlabs/skeleton/styles/skeleton.css';\n
-// Finally, your application's global stylesheet (sometimes labeled 'app.css')
-import '../app.postcss';
-						`}
+
+plugins: [
+	skeleton({
+		themes: {
+			custom: [
+				myCustomTheme
+			]
+		}
+	})
+]
+				`}
 		/>
+		<p>
+			Open <code class="code">/src/app.html</code> and define your theme using the <code class="code">data-theme</code>
+			attribute. The value should match the <code class="code">name</code> field set within your theme's source code.
+		</p>
+		<CodeBlock language="html" code={`<body data-theme="my-custom-theme">`} />
+		<!-- prettier-ignore -->
+		<p>Note that custom themes can be registered along with <a href="/docs/themes#register-themes" class="anchor">Skeleton's preset themes</a>, allowing you to switch between these as desired.</p>
+	</section>
+
+	<hr />
+
+	<section class="space-y-4">
+		<h2 class="h2">Migrate from v1 to v2</h2>
+		<!-- Alert -->
+		<aside class="alert variant-ghost">
+			<div class="alert-message">
+				<p>
+					Need help migrating your theme from the <strong>v1 CSS format</strong> to the <strong>v2 CSS-in-JS format</strong>? Try this handy
+					conversion tool.
+				</p>
+			</div>
+			<div class="alert-actions">
+				<!-- <a class="btn variant-soft" href="/" target="_blank">View Guide</a> -->
+				<a class="btn variant-filled" href="https://transform.tools/css-to-js" target="_blank">Conversion Tool &rarr;</a>
+			</div>
+		</aside>
 	</section>
 
 	<hr />

diff --git a/sites/skeleton.dev/src/routes/(inner)/docs/get-started/+page.svelte b/sites/skeleton.dev/src/routes/(inner)/docs/get-started/+page.svelte
@@ -4,7 +4,7 @@
 	import SectionInstall from './SectionInstall.svelte';
 	import SectionTailwind from './SectionTailwind.svelte';
 	import SectionThemes from './SectionThemes.svelte';
-	import SectionStylesheets from './SectionStylesheets.svelte';
+	// import SectionStylesheets from './SectionStylesheets.svelte';
 </script>
 
 <LayoutPage>
@@ -18,6 +18,6 @@
 	<hr />
 	<SectionInstall />
 	<SectionTailwind />
-	<SectionStylesheets />
+	<!-- <SectionStylesheets /> -->
 	<SectionThemes />
 </LayoutPage>
diff --git a/sites/skeleton.dev/src/routes/(inner)/docs/get-started/SectionInstall.svelte b/sites/skeleton.dev/src/routes/(inner)/docs/get-started/SectionInstall.svelte
@@ -28,7 +28,7 @@ cd my-skeleton-app
 			{:else if $storeOnboardMethod === 'manual'}
 				<!-- prettier-ignore -->
 				<p>
-					If you have an existing SvelteKit application, skip to installing the Skeleton package from NPM. Otherwise let's begin by creating a new <a class="anchor" href="https://kit.svelte.dev/docs/creating-a-project" target="_blank" rel="noreferrer">SvelteKit project</a>.
+					If you have an existing SvelteKit application, skip to the next step. Otherwise let's create a <a class="anchor" href="https://kit.svelte.dev/docs/creating-a-project" target="_blank" rel="noreferrer">SvelteKit project</a>.
 				</p>
 				<CodeBlock
 					language="console"
@@ -39,12 +39,11 @@ npm install
 		`}
 				/>
 				<!-- Install NPM Package -->
+				<!-- prettier-ignore -->
 				<p>
-					Install the <a class="anchor" href="https://www.npmjs.com/package/@skeletonlabs/skeleton" target="_blank" rel="noreferrer"
-						>Skeleton package</a
-					> from NPM.
+					Install the packages for <a class="anchor" href="https://www.npmjs.com/package/@skeletonlabs/skeleton" target="_blank" rel="noreferrer">Skeleton</a> and the <a class="anchor" href="https://www.npmjs.com/package/@skeletonlabs/tw-plugin" target="_blank" rel="noreferrer">Skeleton Tailwind plugin</a>.
 				</p>
-				<CodeBlock language="console" code={`npm i @skeletonlabs/skeleton --save-dev`} />
+				<CodeBlock language="console" code={`npm i -D @skeletonlabs/skeleton @skeletonlabs/tw-plugin`} />
 			{/if}
 		</svelte:fragment>
 	</TabGroup>

diff --git a/sites/skeleton.dev/src/routes/(inner)/docs/get-started/SectionTailwind.svelte b/sites/skeleton.dev/src/routes/(inner)/docs/get-started/SectionTailwind.svelte
@@ -2,6 +2,9 @@
 	import { storeOnboardMethod } from '$lib/stores/stores';
 	// Components
 	import { Tab, TabGroup, CodeBlock } from '@skeletonlabs/skeleton';
+
+	// Local
+	let tabConfigFormat = 'cjs';
 </script>
 
 <!-- Header -->
@@ -33,24 +36,46 @@
 					</p>
 					<CodeBlock language="console" code={`npx svelte-add@latest tailwindcss\nnpm install`} />
 					<!-- prettier-ignore -->
-					<p>Then open your global stylesheet in <code class="code">/src/app.postcss</code> and remove the following three <a class="anchor" href="https://tailwindcss.com/docs/functions-and-directives" target="_blank" rel="noreferrer">@tailwind directives</a> introduced by Svelte-Add. These are redundant as Skeleton automatically handles these in our stylesheets for you.</p>
-					<div class="space-y-[1px]">
-						<del class="del">@tailwind base;</del>
-						<del class="del">@tailwind components;</del>
-						<del class="del">@tailwind utilities;</del>
-					</div>
+					<p>
+						Then open your global stylesheet in <code class="code">/src/app.postcss</code> and ensure the following
+						<a class="anchor" href="https://tailwindcss.com/docs/functions-and-directives" target="_blank" rel="noreferrer">@tailwind directives</a> are present. Svelte-Add will implement this for you automatically.
+					</p>
+					<CodeBlock
+						language="css"
+						code={`
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+@tailwind variants;\n
+/* (your custom styles here) */
+					`}
+					/>
 				</div>
-				<p>Apply these following three changes to your <code class="code">tailwind.config.cjs</code>, found in the root of your project.</p>
-				<CodeBlock
-					language="js"
-					code={`
+				<h3 class="h3">Tailwind Configuration</h3>
+				<p>Apply the following changes to your <code class="code">tailwind.config.[cjs|js|ts]</code>, found in the root of your project.</p>
+				<TabGroup regionPanel="space-y-4">
+					<!-- Tabs -->
+					<Tab bind:group={tabConfigFormat} name="cjs" value="cjs">CommonJS (.cjs)</Tab>
+					<Tab bind:group={tabConfigFormat} name="js" value="js">Javascript (.js)</Tab>
+					<Tab bind:group={tabConfigFormat} name="ts" value="ts">Typescript (.ts)</Tab>
+					<!-- Panel -->
+					<svelte:fragment slot="panel">
+						{#if tabConfigFormat === 'cjs'}
+							<CodeBlock
+								language="cjs"
+								code={`
+// @ts-check
+
+// 1. Import the Skeleton plugin
+const { skeleton } = require('@skeletonlabs/tw-plugin');
+
 /** @type {import('tailwindcss').Config} */
 module.exports = {
-	// 1. Apply the dark mode class setting:
+	// 2. Opt for dark mode to be handled via the class method
 	darkMode: 'class',
 	content: [
 		'./src/**/*.{html,js,svelte,ts}',
-		// 2. Append the path for the Skeleton NPM package and files:
+		// 3. Append the path to the Skeleton package
 		require('path').join(require.resolve(
 			'@skeletonlabs/skeleton'),
 			'../**/*.{html,js,svelte,ts}'
@@ -60,28 +85,98 @@ module.exports = {
 		extend: {},
 	},
 	plugins: [
-		// 3. Append the Skeleton plugin to the end of this list
-		...require('@skeletonlabs/skeleton/tailwind/skeleton.cjs')()
+		// 4. Append the Skeleton plugin (after other plugins)
+		skeleton
+	]
+}
+						`}
+							/>
+						{:else if tabConfigFormat === 'js'}
+							<CodeBlock
+								language="js"
+								code={`
+// @ts-check
+import { join } from 'path';
+
+// 1. Import the Skeleton plugin
+import { skeleton } from '@skeletonlabs/tw-plugin';
+
+/** @type {import('tailwindcss').Config} */
+export default {
+	// 2. Opt for dark mode to be handled via the class method
+	darkMode: 'class',
+	content: [
+		'./src/**/*.{html,js,svelte,ts}',
+		// 3. Append the path to the Skeleton package
+		join(require.resolve(
+			'@skeletonlabs/skeleton'),
+			'../**/*.{html,js,svelte,ts}'
+		)
+	],
+	theme: {
+		extend: {},
+	},
+	plugins: [
+		// 4. Append the Skeleton plugin (after other plugins)
+		skeleton
 	]
 }
-`}
-				/>
-				<aside class="alert variant-ghost-warning">
+						`}
+							/>
+						{:else}
+							<CodeBlock
+								language="ts"
+								code={`
+import { join } from 'path';
+import type { Config } from 'tailwindcss';
+
+// 1. Import the Skeleton plugin
+import { skeleton } from '@skeletonlabs/tw-plugin';
+
+const config = {
+	// 2. Opt for dark mode to be handled via the class method
+	darkMode: 'class',
+	content: [
+		'./src/**/*.{html,js,svelte,ts}',
+		// 3. Append the path to the Skeleton package
+		join(require.resolve(
+			'@skeletonlabs/skeleton'),
+			'../**/*.{html,js,svelte,ts}'
+		)
+	],
+	theme: {
+		extend: {},
+	},
+	plugins: [
+		// 4. Append the Skeleton plugin (after other plugins)
+		skeleton
+	]
+} satisfies Config;
+
+export default config;
+						`}
+							/>
+						{/if}
+					</svelte:fragment>
+				</TabGroup>
+
+				<!-- <aside class="alert variant-ghost-warning">
 					<i class="fa-solid fa-triangle-exclamation text-2xl" />
 					<div class="alert-message">
 						Skeleton's Tailwind plugin cannot operate alongside plugins from other UI libraries, such as <strong>Flowbite</strong> or
 						<strong>Daisy</strong>. All three plugins modify similar settings, which means they will conflict.
 					</div>
-				</aside>
+				</aside> -->
+				<h3 class="h3">Dark Mode Support</h3>
 				<p>
-					Note that your app will default to light mode. To manually set dark mode, append the following class to the HTML element within <code
-						class="code">/src/app.html</code
-					>.
+					Note that your app will default to light mode. If you wish to default to dark mode, append the following class to the HTML element
+					within <code class="code">/src/app.html</code>. View
+					<a class="anchor" href="https://tailwindcss.com/docs/dark-mode" target="_blank">Tailwind's documentation</a> for more information.
 				</p>
 				<CodeBlock language="html" code={`<html class="dark">`} />
 				<p>
-					If you wish to be able to toggle dark mode, review the <a class="anchor" href="/utilities/lightswitches">Lightswitch</a> utility features
-					when you complete this setup process.
+					Skeleton also provides a <a class="anchor" href="/utilities/lightswitches" target="_blank">Lightswitch</a> utility if you wish toggle
+					between light and dark modes.
 				</p>
 			{/if}
 		</svelte:fragment>