Getting started ​

Installation ​

Firstly, you'll need a project that has:

• Vue 3
• Vite
• (optional) Unplugin Icons (or another way to use Material Design icons)
• (optional) Vue Router

Then, install Halcyon:

pnpm add halcyon-vue
# or:
yarn add halcyon-vue
# or:
pnpm install halcyon-vue

pnpm add halcyon-vue
# or:
yarn add halcyon-vue
# or:
pnpm install halcyon-vue

Theme creation (optional) ​

You should use the Material Theme Builder to generate a theme. Once you've done that, you can download the JSON file and use it in your project.

Vite setup ​

Load the plugin within your Vite config:

import { defineConfig } from 'vite'
import { Halcyon } from 'halcyon-vue/plugin'
import theme from './theme.json' // the theme you created in the last step
// ...
export default defineConfig({
    plugins: [
        // ...
        Halcyon({ theme })
    ]
})

import { defineConfig } from 'vite'
import { Halcyon } from 'halcyon-vue/plugin'
import theme from './theme.json' // the theme you created in the last step
// ...
export default defineConfig({
    plugins: [
        // ...
        Halcyon({ theme })
    ]
})

If a custom theme is not passed in, the default theme will be used.

Font setup (optional) ​

It's not required, but you should import a couple fonts for the most accurate experience. In particular, Roboto Flex (or Roboto if your target doesn't support variable fonts) and Noto Sans (as a fallback font) are used. Here's a snippet you can put into your index.html to import Roboto Flex and Noto Sans:

<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,500;0,700;1,400;1,500;1,700&family=Roboto+Flex:wght@400;500;700&display=swap" rel="stylesheet">

<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,500;0,700;1,400;1,500;1,700&family=Roboto+Flex:wght@400;500;700&display=swap" rel="stylesheet">

(This snippet probably imports more than you'll need, so consider selecting the fonts on Google Fonts yourself.)

Vue setup ​

In the file where you set up Vue (i.e. main.js or main.ts), import the stylesheets:

import 'halcyon:reset.css' // optional if you're already using a css reset
import 'halcyon:theme.css' // sets up the theme variables
import 'halcyon:base.css'  // includes global styles (e.g. body)
import 'halcyon-vue/style' // includes component styles

import 'halcyon:reset.css' // optional if you're already using a css reset
import 'halcyon:theme.css' // sets up the theme variables
import 'halcyon:base.css'  // includes global styles (e.g. body)
import 'halcyon-vue/style' // includes component styles

Now you can use the components in your app!

Usage ​

Here's an example of how to use a button:

<script setup>
import { HButton } from 'halcyon-vue'

const alert = (msg) => window.alert(msg) // vue why
</script>
<template>
    <div>
        <HButton
            kind="filled"
            content="Press me!"
            @click="alert('yippee')"
        />
    </div>
</template>

<script setup>
import { HButton } from 'halcyon-vue'

const alert = (msg) => window.alert(msg) // vue why
</script>
<template>
    <div>
        <HButton
            kind="filled"
            content="Press me!"
            @click="alert('yippee')"
        />
    </div>
</template>

This renders the following button: