Define developer principles

[joshwooding]

Whilst building components there are certain things we want to keep consistent or think about when designing APIs. We should document these and share them.

cc @jpmorganchase/salt-dev

[el-dav]

Some potential topics:

• Polymorphism

  • e.g. <Button as="div" />
  • Should all components have it?
  • Standard patterns for building typing

• Responsive properties

  • e.g. <Stack direction={{ xs: 'row', lg: 'column' }} />
  • What components/props should we use it (if any)
  • How to implement it

• Should we have a primitive <Box /> component

  • To allow consumers to hook into our design tokens
  • E.g. in Braid, Chakra UI, or MUI
  • If not, how can we make it easy for consumers to stick to our design principles in their own components?

• Any standard patterns for creating a Salt component e.g.

  • forwardRef
  • memo
  • class name (withBaseName)

• CSS standards

  • class names
  • css variable names
  • css variable patterns
    • allowing overrides
    • internal css variables
  • consuming characteristics
  • Should every component add a className e.g. if <Stack> uses <Flex> under the hood should it add a stack class even if it's not required for the implementation?

• TS standards e.g.

  • Extending other components (import types directly or use ComponentPropsWithoutRef)
  • What types to export to consumers
  • etc

• API design

  • config props vs composition
  • approach to complexity (do we aim for simplest version of a component initially)

• Refs

  • What element to forward ref to
  • If forwardRef is passed to non-root element should we have another prop to access the root ref?

• Testing standards

• Storybook standards

• Documentation standards

• PR process

  • Number of reviewers
  • Who should review
  • etc

• How do we deprecate features/props/components

[libertymayc]

CSS standards is one we have discussed a lot, I should move over the confluence notes(/stuff in my head :P) to GitHub as well, and we should discuss overrides in more detail when/if we start encouraging it, and +1 on discussing the last point there too

[el-dav]

CSS standards is one we have discussed a lot, I should move over the confluence notes(/stuff in my head :P) to GitHub as well, and we should discuss overrides in more detail when/if we start encouraging it, and +1 on discussing the last point there too

Yeah sorry, I was including topics for documenting on github in case of new starters or outside contributions

[el-dav]

Created an RFC with a potential implementation of responsive props: https://github.com/jpmorganchase/salt-ds/pull/1158

[el-dav]

• Polymorphism
  • e.g. <Button as="div" />
  • Should all components have it?
  • Standard patterns for building typing

[el-dav]

• Responsive properties
  • e.g. <Stack direction={{ xs: 'row', lg: 'column' }} />
  • What components/props should we use it (if any)
  • How to implement it
  • See proposal here: https://github.com/jpmorganchase/salt-ds/pull/1158

[el-dav]

• Any standard patterns for creating a Salt component e.g.
  • forwardRef
  • memo
  • class name (withBaseName)

[el-dav]

• CSS standards
  • class names
  • css variable names
  • css variable patterns
    • allowing overrides
    • internal css variables
  • consuming characteristics
  • Should every component add a className e.g. if <Stack> uses <Flex> under the hood should it add a stack class even if it's not required for the implementation?
  • (we've discussed quite a bit already but should get it documented)

[el-dav]

• TS standards e.g.
  • Extending other components (import types directly or use ComponentPropsWithoutRef)
  • What types to export to consumers
  • etc

[el-dav]

• API design
  • config props vs composition
  • approach to complexity (do we aim for simplest version of a component initially)

[el-dav]

• Refs
  • What element to forward ref to
  • If forwardRef is passed to non-root element should we have another prop to access the root ref?

[el-dav]

• Testing standards

[el-dav]

• Storybook standards

[el-dav]

• Documentation standards

[el-dav]

• PR process
  • Number of reviewers
  • Who should review
  • etc

[el-dav]

• How do we deprecate features/props/components

[joshwooding]

• Should we have a primitive <Box /> component

  • To allow consumers to hook into our design tokens
  • E.g. in Braid, Chakra UI, or MUI
  • If not, how can we make it easy for consumers to stick to our design principles in their own components?

@el-dav I think this is a separate discussion and deserves its own issue