# Stratosphere Standards

These are additional standards specific to the cirrus-stratus-component-library repo. Please also follow the guidelines set in the Frontend Standards.

# Goals

The goal of the design system is to centralize the UI concerns of CI applications. The design system is intended to supply UI components, css variables, fonts, icons, and documentation to be consumed in every Vue.js app used at CI.

# Components

Create a UI Component in the design system whenever something is needed in multiple views or apps
Every UI component should be universal and agnostic to the feature or use case its used in
UI components shouldn’t be concerned about managing data or error handling. They will just render a UI based on the props set and expose events
In most cases, components should not have margins baked in
UI Components should not be customized by other apps. For example, you should never change the text color of a button. Instead, that change should be made in the design system through new props, components, et
Leverage provide/inject for parent/child communication when possible to reduce manual errors and other complications with scoped slots
Writing Component Vue & Javascript
❗️Include Jsdoc comments for every prop, slot and event. These will be used for automated prop/slot/event tables in a documentation website
Avoid mixins. Instead, abstract things into methods, types, or interfaces
Keep logic out of the template markup by using clear computed properties

// Bad
<h1 v-if="title || $route.params.title && showTitle">
  {{ title || $route.params.title }}
</h1>

// Good
<h1 v-if="hasTitle">
  {{ titleText }}
</h1>

Parent components should only allow for child components to be used in their slots. The Vnodes.ts helper can handle this
Child components should throw an error when not contained in a parent

# Component Props

❗️Include Jsdoc comments for every prop. These will be used for automated tables in a documentation website in the future.
Support the default attributes of html elements whenever possible
Do not rewrite existing html attributes as props unless absolutely necessary
Favor slots over strings when the design rules or use cases are unclear. Name a slot and prop the same name if either can be used.

<slot name="title">
  {{ title }}
</slot>

Be thoughtful about when a prop has a default or is required
Prefer validated string over multiple Boolean props

// Bad
@Prop({ type: Boolean, default: false })
small!: boolean;
@Prop({ type: Boolean, default: false })
medium!: boolean;
@Prop({ type: Boolean, default: false })
large!: boolean;

// Good
import { CiSpacing, CiSpacingArray } from '../component-spacing';
import { oneOfOptions } from "../../helpers/PropertyValidators";
...
@Prop({
  type: String,
  default: 'md',
  validator: oneOfOptions(CiSpacingArray)
})
spacing!: CiSpacing

❗️Never create a prop for things like color, size, spacing that accepts an arbitrary value, as that prevents the design system from strictly controlling ui styles

// BAD
<my-component color="#ff0000" />

// GOOD
<my-component variant="error" />

# Component Events

Use simple singular names whenever possible

// BAD
@input-change
@on-input
@select:input

// GOOD
@input

Prefix with componentName: when necessary

@input
@tagList:input

# Component Styles

never style one element from within another. Instead, keep all styles separate

// Bad
.my-component {
  &.disabled {
    .my-component__child {
      ...
    }
  }
  &__child {
    ...
  }
}

// Good
.my-component {
  &.disabled {
    ...
  }
  &__child {
    &.disabled {
      ...
    }
  }
}

# Component Documentation

In order to make sure the component is functioning correctly, and to ensure that an engineer looking at the docs knows what the component does, create a demo for…

each prop. If relevant, show the variations of a prop. for example, for a size prop show all sizes
each slot. Every slot should be used in a demo.
each event. Create a demo that uses the event to do something

← Local Development