Update Getting Started and Customization docs

techniq · Feb 6, 2024 · d863d6e · d863d6e
1 parent 0be9dd5
commit d863d6e
Show file tree

Hide file tree

Showing 4 changed files with 431 additions and 142 deletions.
diff --git a/packages/svelte-ux/src/routes/+page.md b/packages/svelte-ux/src/routes/+page.md
diff --git a/packages/svelte-ux/src/routes/+page.svelte b/packages/svelte-ux/src/routes/+page.svelte
@@ -0,0 +1,172 @@
+<script lang="ts">
+  import Code from '$lib/components/Code.svelte';
+  import Kbd from '$lib/components/Kbd.svelte';
+  import ToggleGroup from '$lib/components/ToggleGroup.svelte';
+  import ToggleOption from '$lib/components/ToggleOption.svelte';
+
+  let selectedTab = 'cli';
+</script>
+
+<div class="prose max-w-none bg-surface-100 rounded border p-4 mt-4 m-2">
+  <h1>Getting started</h1>
+
+  <h2>Installation</h2>
+  <ToggleGroup
+    bind:value={selectedTab}
+    variant="underline"
+    classes={{ options: 'justify-start h-10 mb-3' }}
+  >
+    <ToggleOption value="cli">CLI</ToggleOption>
+    <ToggleOption value="svelte-add">Svelte Add</ToggleOption>
+    <ToggleOption value="manual">Manual Install</ToggleOption>
+  </ToggleGroup>
+
+  <div class="grid gap-3">
+    {#if selectedTab === 'cli'}
+      <div>
+        Start a new SvelteKit project preconfigured with Tailwind and Svelte UX using the
+        <code>create-svelte-ux</code> CLI
+      </div>
+
+      <Code source={`npm create svelte-ux@latest`} language="sh" />
+
+      <div>
+        There are a few templates to choose from, including one which includes <a
+          href="https://www.layerchart.com"
+          target="_blank">LayerChart</a
+        >
+      </div>
+    {:else if selectedTab === 'svelte-add'}
+      <div>Start a new project SvelteKit project</div>
+      <Code source={`npm create svelte@latest`} language="sh" />
+
+      <div>Add Svelte UX package</div>
+      <Code source={`npm install svelte-ux`} language="sh" />
+
+      <div>
+        Add and setup Tailwind using <a
+          href="https://github.com/svelte-add/tailwindcss"
+          target="_blank"
+        >
+          svelte-add
+        </a>
+      </div>
+      <Code source={`npx svelte-add@latest tailwindcss`} language="sh" />
+    {:else if selectedTab === 'manual'}
+      <div>
+        Follow the Tailwind <a href="https://tailwindcss.com/docs/guides/sveltekit" target="_blank">
+          guide
+        </a> to setup a new SvelteKit project with Tailwind.
+      </div>
+
+      <div>Add Svelte UX package</div>
+      <Code source={`npm install svelte-ux`} language="sh" />
+    {/if}
+
+    {#if selectedTab === 'svelte-add' || selectedTab === 'manual'}
+      <div>Update <code>tailwind.config.cjs</code></div>
+      <Code
+        source={`const colors = require('tailwindcss/colors');
+const plugin = require('tailwindcss/plugin');
+
+const svelteUx = require('./src/lib/plugins/tailwind.cjs');
+
+module.exports = {
+  content: [
+    './src/**/*.{html,svelte}', 
+    './node_modules/svelte-ux/**/*.{svelte,js}'
+  ],
+  ux: {
+    // See customization docs
+    themes: {
+      light: {
+        primary: colors['orange']['500'],
+        'primary-content': 'white',
+        secondary: colors['blue']['500'],
+        'surface-100': 'white',
+        'surface-200': colors['gray']['100'],
+        'surface-300': colors['gray']['300'],
+        'surface-content': colors['gray']['900'],
+        'color-scheme': 'light'
+      },
+      dark: {
+        primary: colors['orange']['500'],
+        'primary-content': 'white',
+        secondary: colors['blue']['500'],
+        'surface-100': colors['zinc']['800'],
+        'surface-200': colors['zinc']['900'],
+        'surface-300': colors['zinc']['950'],
+        'surface-content': colors['zinc']['100'],
+        'color-scheme': 'dark'
+      },
+    },
+  },
+  plugins: [
+    svelteUx, // Can also call with colorSpace options
+  ]
+};`}
+        language="js"
+      />
+    {/if}
+  </div>
+
+  <p>A few notes regarding the <code>tailwind.config.cjs</code></p>
+
+  <ul>
+    <li>
+      <code>{`./node_modules/svelte-ux/**/*.{(svelte, js)}`}</code> adds the library classes via
+      <a href="https://tailwindcss.com/docs/content-configuration">JIT</a>
+    </li>
+    <li>
+      <code>ux.themes</code> is used to configure the theme colors. See
+      <a href="/customization">customization</a> for more details.
+    </li>
+    <li>
+      Tailwind plugin injects the theme color variables, sets border, outline, ring, and typograpy
+      defauls based on the theme, and adds additional utility classes including:
+      <ul>
+        <li>
+          <code>elevation-#</code> for
+          <a
+            class="text-primary font-medium"
+            href="https://www.joshwcomeau.com/css/designing-shadows/"
+            rel="nofollow">realistic shadows</a
+          >
+          using multiple shadow layers, unlike the current Tailwind
+          <a
+            class="text-primary font-medium"
+            href="https://tailwindcss.com/docs/box-shadow"
+            rel="nofollow">shadows</a
+          >
+          which have at most 2 layers.
+        </li>
+        <li>
+          <code>grid-stack</code> to easily stack grid children
+        </li>
+        <li>
+          <code>scrollbar-none</code> to hide the scrollbar
+        </li>
+      </ul>
+    </li>
+  </ul>
+
+  <h2>Usage</h2>
+
+  <p>
+    Using <code>components</code>, <code>actions</code>, <code>stores</code>, or <code>utils</code>
+    are as simple as importing from <code>svelte-ux</code>.
+  </p>
+
+  <Code
+    source={`<script>
+  import { Button } from 'svelte-ux';
+</script>
+
+<Button>Click here</Button>`}
+    language="svelte"
+  />
+
+  <p>
+    Search docs using <Kbd command class="text-xs">K</Kbd> or browse using the sidebar navigation.
+  </p>
+</div>
diff --git a/packages/svelte-ux/src/routes/customization/+layout.svelte b/packages/svelte-ux/src/routes/customization/+layout.svelte
@@ -1,3 +1,20 @@
-<div class="prose max-w-none p-4 bg-surface-100">
-  <slot />
+<script lang="ts">
+  import TableOfContents from '$lib/components/TableOfContents.svelte';
+</script>
+
+<div class="grid grid-cols-[1fr,auto] gap-6 pt-2 pb-4">
+  <div class="bg-surface-100 p-4 m-2 rounded shadow-lg border overflow-auto">
+    <div class="prose max-w-none">
+      <slot />
+    </div>
+  </div>
+
+  <div class="hidden lg:block w-[224px]">
+    <div class="sticky top-0 pr-2 max-h-[calc(100vh-64px)] overflow-auto">
+      <div class="text-xs uppercase leading-8 tracking-widest text-surface-content/50">
+        On this page
+      </div>
+      <TableOfContents />
+    </div>
+  </div>
 </div>