@octaviaflow/type 1.0.0

package/README.md

@@ -0,0 +1,239 @@
+# @octaviaflow/type
+
+> Typography for digital and software products using the Carbon Design System
+
+## Getting started
+
+To install `@octaviaflow/type` in your project, you will need to run the following
+command using [npm](https://www.npmjs.com/):
+
+```bash
+npm install -S @octaviaflow/type
+```
+
+If you prefer [Yarn](https://yarnpkg.com/en/), use the following command
+instead:
+
+```bash
+yarn add @octaviaflow/type
+```
+
+## Usage
+
+`@octaviaflow/type` provides a variety of ways to work with typography from the IBM
+Design Language. You can use all of these features either in JavaScript or Sass.
+These features include:
+
+| Feature                       | Description                                                                                                   |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| [Font face](#font-face)       | Include IBM Plex™ font faces in your application. Uses Akamai CDN                                            |
+| [Type classes](#type-classes) | Helpers to use type styles directly. Not included by default                                                  |
+| [Font family](#font-family)   | Defines the font stack for IBM Plex™ in your application, provides helpers for working with font definitions |
+| [Reset](#reset)               | Provides a high-level CSS Reset to use in your project                                                        |
+| [Scale](#type-scale)          | Provides the type scale. Can access the size at any given step (step 1, 2, 3, etc)                            |
+| [Styles](#type-styles)        | Provides type styles for your application (heading-01, body-long-01, etc)                                     |
+
+The `@octaviaflow/type` package enables you to use typography from the IBM Design
+Language, including the type scale and fonts, along with typography design
+tokens from the Carbon Design System. It also comes with opinionated defaults
+for type styles on common elements like `h1`, `h2`, `p`, etc.
+
+You can use this package by writing the following:
+
+```scss
+@use '@octaviaflow/type';
+
+// Include type reset
+@include type.reset();
+
+// Include default type styles, targets h1, h2, h3, etc
+@include type.default-type();
+
+// Include utility classes for type-related properties
+@include type.type-classes();
+
+.selector {
+  // Include a type style
+  @include type.type-style('productive-heading-01');
+}
+```
+
+This should include the default type reset from the project, in addition to
+font-face definitions for IBM Plex Mono and IBM Plex Sans that come from Google
+Fonts.
+
+If you are using `@octaviaflow/react`, the import paths become:
+
+```scss
+@use '@octaviaflow/react/scss/type';
+```
+
+### Type styles
+
+Instead of using a type scale, `@octaviaflow/type` provides tokens that represent
+what we call type styles. These tokens have a variety of properties for styling
+how text is rendered on a page.
+
+You can find a full reference of the type styles that are available on the
+[Carbon Design System website](https://www.carbondesignsystem.com/guidelines/typography/type-sets)
+.
+
+You can include a token in your Sass file by writing:
+
+```scss
+@use '@octaviaflow/type';
+
+@include type.type-style('token-name');
+```
+
+In addition, if the type style you are using has a fluid style then you can pass
+in `true` as the second argument to `type-style` to enable fluid styles. For
+example:
+
+```scss
+@use '@octaviaflow/type';
+
+@include type.type-style('token-name', true);
+```
+
+### Type classes
+
+The recommended way to style your application will be to use our
+[type styles](#type-styles). However, we also offer helper CSS classes for
+specific use-cases. These are also helpful when quickly prototyping a project.
+
+You can include type classes in your project by writing the following in your
+Sass file:
+
+```scss
+@use '@octaviaflow/type';
+
+:root {
+  @include type.type-classes();
+}
+```
+
+And then add the appropriate classes to the element you want to style
+
+```html
+<span className="cds--type-mono">Test sentence</span>
+```
+
+| Selector                  | Description                               |
+| ------------------------- | ----------------------------------------- |
+| `.cds--type-mono`         | Specify the font face as IBM Plex Mono    |
+| `.cds--type-sans`         | Specify the font face as IBM Plex Sans    |
+| `.cds--type-serif`        | Specify the font face as IBM Plex Serif   |
+| `.cds--type-light`        | Specify the font weight as light (300)    |
+| `.cds--type-regular`      | Specify the font weight as regular (400)  |
+| `.cds--type-semibold`     | Specify the font weight as semibold (600) |
+| `.cds--type-italic`       | Specify the font style as italic          |
+| `.cds--type-<type-style>` | Set styles for the given type style       |
+
+### Font family
+
+`@octaviaflow/type` provides the font stacks for all the IBM Plex fonts available.
+You can access the font family information by including the following import in
+your Sass file:
+
+```scss
+@use '@octaviaflow/type';
+```
+
+The font stacks are available under the `$font-families` variable. You can also
+access a specific font family by using the `font-family` function by doing:
+
+```scss
+.my-selector {
+  font-family: type.font-family('mono');
+}
+```
+
+You can also use the `font-family` mixin to automatically set the `font-family`
+property for you:
+
+```scss
+.my-selector {
+  @include type.font-family('serif');
+}
+```
+
+You can see all the available font families in `$font-families` .
+
+### Reset
+
+An optional type reset is provided under the `reset` mixin. You can include this
+mixin by writing the following in your Sass file:
+
+```scss
+@use '@octaviaflow/type';
+
+:root {
+  @include type.reset();
+}
+```
+
+This reset sets some top-level properties on `html` and `body`, namely
+`font-size`, `font-family`, and some `text-rendering` options. We also map the
+`strong` tag to the semibold font weight.
+
+### Type scale
+
+A type scale is provided through the `$type-scale` variable and corresponding
+`type-scale` function and mixin. However, for specifying type styles, the
+recommendation is to use [type styles](#type-styles) .
+
+If you are looking to use the type scale, you can include all the scale-related
+utilities and variables by writing the following in your Sass file:
+
+```scss
+@use '@octaviaflow/type';
+```
+
+You can access a specific step in the type scale by using the `type-scale`
+function:
+
+```scss
+.my-selector {
+  font-size: type.type-scale(1);
+}
+```
+
+There is also a `type-scale` mixin that will set `font-size` for your directly:
+
+```scss
+@use '@octaviaflow/type';
+
+.my-selector {
+  @include type.type-scale(4);
+}
+```
+
+## 📚 Examples
+
+If you're looking for more examples on how to use `@octaviaflow/type`, we have some
+examples that you can check out:
+
+- [Stackblitz](https://stackblitz.com/edit/github-wdcdqx?file=src%2Findex.scss)
+
+You can also see more documentation regarding the available tokens
+[here](./docs/sass.md)
+
+## 🙌 Contributing
+
+We're always looking for contributors to help us fix bugs, build new features,
+or help us improve the project documentation. If you're interested, definitely
+check out our [Contributing Guide](/.github/CONTRIBUTING.md)! 👀
+
+## 📝 License
+
+Licensed under the [Apache 2.0 License](/LICENSE).
+
+## <picture><source height="20" width="20" media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ibm-telemetry/telemetry-js/main/docs/images/ibm-telemetry-dark.svg"><source height="20" width="20" media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/ibm-telemetry/telemetry-js/main/docs/images/ibm-telemetry-light.svg"><img height="20" width="20" alt="IBM Telemetry" src="https://raw.githubusercontent.com/ibm-telemetry/telemetry-js/main/docs/images/ibm-telemetry-light.svg"></picture> IBM Telemetry
+
+This package uses IBM Telemetry to collect de-identified and anonymized metrics
+data. By installing this package as a dependency you are agreeing to telemetry
+collection. To opt out, see
+[Opting out of IBM Telemetry data collection](https://github.com/ibm-telemetry/telemetry-js/tree/main#opting-out-of-ibm-telemetry-data-collection).
+For more information on the data being collected, please see the
+[IBM Telemetry documentation](https://github.com/ibm-telemetry/telemetry-js/tree/main#ibm-telemetry-collection-basics).